First of all, how do I know if visualization and changeset tracking is already enabled for a given branch?

Great question!  If you have just upgraded your existing TFS 2008 server then you likely don’t have any these features enabled for any of your branches yet because we don’t try to detect them on upgrade.  To make this example a little more concrete, let’s assume you have two branches where you are developing prototypes under the path $/MyProduct/features/Feature1/prototypes.  We can determine if these branches have visualizations enabled by navigating to that folder in Source Control Explorer:

In Source Control Explorer and a few other places the branch visualization status of a folder is represented by its icon.  Even though the Jupiter and Saturn folders above were both created by the branch command, only Saturn has visualizations enabled and this is can be determined by looking at their respective icons. 

Cool, so how do I enable visualizations for the Jupiter branch?

Start by right-clicking on the Jupiter folder, selecting Branching and Merging and then clicking on Convert to Branch….  This will bring up the following dialog:

At this point you can enter a description for the work that is being done in this branch before converting it.  You should also notice the check box at the bottom of the dialog that reads “Recursively perform this conversion on all folders previously branched from this folder”.  As you might have guessed, this option will recursively convert all of the folders that are child branches of this folder when the conversion is done.  If for some reason, you want to cherry-pick which branches you enable visualizations on then unchecking this box is a good idea.  Now, if we click convert, we will see that the icon for the Jupiter folder now indicates that it has visualizations enabled:

But when I tried to do that, I got an error reading “TF203028: You cannot create a branch at $/x because a branch already exists at $/x/y”.

Obviously, in a branch hierarchy, branches can have child branches and parent branches.  However, what a branch cannot have is a folder beneath it in the source control repository that is also a branch.  Thus, in our example, if Jupiter would have had a child folder that had already been converted to a branch we would have received this error.  In TFS 2010, when you perform a branch from the UI, the option to “convert source and target folders to branches” is enabled by default if neither of these folder have a parent folder that is a branch.  Thus, if you haven’t enabled visualizations for your existing branches then it is possible to accidentally create these spurious branches.  If we still want to convert Jupiter to be a branch we will need to convert the offending child folder which is marked as a branch back to a normal folder.  This can be done by selecting the offending child folder then clicking File > Source Control > Branching and Merging > Convert To Folder.  You will receive a prompt to confirm the action you are performing and after confirming it then you should be able to convert the desired parent folder to a branch.

Once you have done that to all of your branches then you can visualize your branch hierarchies by right-clicking on a node and selecting Branching and Merging > View Hierarchy.  By changing the “Show:” drop down menu to have the value “All hierarchies” I was able to generate this diagram:

Unfortunately, its at this point that I notice that the Feature3 branch has the incorrect parent.  While it was originally branched from the Product1 branch we subsequently did a baseless merge with the Product2 branch because we changed our minds about where Feature3 was actually going to live.  Fortunately, there is a way to fix this!  By selecting the Feature3 branch in this view and then clicking File > Source Control > Branching and Merging > Reparent… you will be presented by a dialog that allows you to choose the branches correct parent.  Note, this dialog will only show branches that this branch has a merge relationship with.  Upon completing the reparenting, my diagram now correctly shows Feature3 with the correct parent (that being Product2):

Doing All of This Programmatically

Now let’s say that you do want to cherry-pick the branches that you want to convert and you have too many branches to convert by hand.  Fortunately, we can combat this problem with a command line tool that uses some of the APIs new in TFS 2010.  I will walk you through those APIs here.

In order to use the code from the examples in this post you will need the following include statements:

using System;
using System.Collections.Generic;
using System.Linq;
using Microsoft.TeamFoundation.Client;
using Microsoft.TeamFoundation.VersionControl.Client;

First, let’s talk about the input to this command-line tool because we will need to know the list of branches that you want convert.  For my example I am going to use an xml document formatted in the following way:

<BranchSpecs>
    <BranchSpec path="$/MyProduct/Main" 
                owner="taylaf" description="The main branch" />
    <BranchSpec path="$/MyProduct/Product1" 
                owner="taylaf" description="The product1 branch" />
    <BranchSpec path="$/MyProduct/Product2" 
                owner="taylaf" description="The product2 branch" />
    <BranchSpec path="$/MyProduct/features/Feature1" 
                owner="taylaf" description="The feature1 branch" />
    <BranchSpec path="$/MyProduct/features/Feature2" 
                owner="taylaf" description="The feature2 branch" />
    <BranchSpec path="$/MyProduct/features/Feature3" overrideParentPath="$/MyProduct/Product2" 
                owner="taylaf" description="The feature3 branch" />
    <BranchSpec path="$/MyProduct/features/prototypes/Jupiter" 
                owner="taylaf" description="The jupiter branch" />
    <BranchSpec path="$/MyProduct/features/prototypes/Saturn" 
                owner="taylaf" description="The saturn branch" />
</BranchSpecs>

You will notice that the $/MyProduct/features/Feature3 is the only branch that has the overrideParentPath attribute set.  This is due to the fact that we want to override what the parent branch is set to when we create the branch objects.  You should know the story as to why we want to do this override if you have read the whole blog post thus far.  If not, you may want to read the section in between the two branch hierarchy screen shots above.  Using some xml parsing magic (which I will leave up to the user to figure out :)) I am going to populate an instance of the following class for each of the BranchSpec entries:

public class BranchSpec
{
    public String Path { get; set; }
    public String OverrideParentPath { get; set; }
    public String Owner { get; set; }
    public String Description { get; set; }
}

Using this class I will produce the list of BranchSpecs that show up in the rest of the example.  Feel free to use whichever input method works best for you.

Now that we have the data we need to do the processing, let’s start with the basics.  We will need a connection to the server that we are going to be converting the branches on as well as a link to the version control client OM entry point:

TfsTeamProjectCollection tpc = new TfsTeamProjectCollection(new Uri("http://server:8080/tfs/MyTPC"));
VersionControlServer sourceControl = tpc.GetService<VersionControlServer>();

Before we write the loop that will actually create the branch objects, let’s write some of the meatier parts that will actually be responsible for the branch object creation.  One of the tasks we are going are going to want to perform is to determine the parent branch of the branch we want to convert so that we can set that piece of the metadata on the branch object.  To do this we will write a function to determine the branch parent that uses the GetBranchHistory API.  Here is the code with some explanation in the comments on how to do this:

private String DetermineParentBranchPath(
    VersionControlServer sourceControl, 
    BranchSpec branchSpec)
{
    // Create an ItemSpec for the branch path that we want to determine
    // the parent for.  Make sure to set the RecursionType parameter to
    // None because we only want branch history for the root item.
    ItemSpec itemSpec = new ItemSpec(branchSpec.Path, RecursionType.None);

    // Call GetBranchHistory() on the ItemSpec that we constructed.  We
    // will set the VersionSpec to latest because we know the branch exists
    // at latest.
    BranchHistoryTreeItem[][] results = sourceControl.GetBranchHistory(
        new ItemSpec[] { itemSpec }, VersionSpec.Latest);

    // The results returned from the GetBranchHistory() call are a bit complicated.
    // First of all, we know that the results specific to our query are in the 
    // first entry of the 2D array.  This is because the contract with the method
    // is that it will return an array of BranchHistoryTreeItem for each path that
    // is queried and the entries in the array will be sorted in the order of the
    // input paths.  Let's grab the first element so we can operate on it.
    BranchHistoryTreeItem[] thisBranchResults = results[0];

    // Now that we have our results we need to process them in order to find the
    // branch that we originally queried on.  In order to do that we will want
    // to look at each BranchHistoryTreeItem and each of its children.  Let's 
    // start by iterating over the results.
    foreach (BranchHistoryTreeItem treeItem in thisBranchResults)
    {
        // Now, let's invoke a recursive function on the treeItem to iterate
        // over all of its children to determine if we have found the requested
        // item.
        BranchRelative requestedItem = FindRequestedItem(treeItem);

        // If we found the requested item see if it has an item it was branched from.
        if (requestedItem != null)
        {
            return (requestedItem.BranchFromItem == null) ? null : requestedItem.BranchFromItem.ServerItem;
        }
    }

    return null;
}

private BranchRelative FindRequestedItem(
    BranchHistoryTreeItem treeItem)
{
    // If the current item is the requested item then return the
    // BranchRelative for the item.
    if (treeItem.Relative.IsRequestedItem)
    {
        return treeItem.Relative;
    }

    // Otherwise, iterate over all of the children for this 
    // branch item and call this method on the children.
    foreach (BranchHistoryTreeItem child in treeItem.Children)
    {
        BranchRelative requestedItem = FindRequestedItem(child);
        if (requestedItem != null)
        {
            return requestedItem;
        }
    }

    return null;
}

With the above two methods we can programmatically determine the parent of the current branch.  Of course, it is possible that the branch is a root branch and it does not have a parent.  In that case, null will be returned by DetermineParentBranchPath().  Now, onto making sure the branch exists as a branch object.  In terms of the object-model a branch that has visualizations enabled is referred to as a BranchObject.  For the method that makes sure the branch object exists we will make sure to check to see if it exists first and will update it with the appropriate information if it does exist.  The reason for this will be explained later.  Again, here is the code to do this with explanations in the comments:

private void EnsureBranchObjectExists(
    VersionControlServer sourceControl,
    String path,
    String parentPath,
    String owner,
    String description)
{
    // Create an ItemIdentifier for the path that we will be querying branch objects on.
    ItemIdentifier branchItemIdentifier = new ItemIdentifier(path);

    // Call QueryBranchObjects to determine if a branch object already exists for the
    // given path.  Again, be sure to pass None for the recursion type because we only want to
    // look for the branch object on the item itself.
    BranchObject[] branchObjects = sourceControl.QueryBranchObjects(branchItemIdentifier, RecursionType.None);

    BranchObject branchObject = branchObjects.FirstOrDefault();
    if (branchObject != null)
    {
        // The branch object exists.  Let's make sure it has the correct properties.
        SetBranchProperties(branchObject.Properties, parentPath, owner, description);

        // Now make sure the properties are persisted to the server
        sourceControl.UpdateBranchObject(branchObject.Properties);
    }
    else
    {
        // We need to create the branch object.
        BranchProperties properties = new BranchProperties(branchItemIdentifier);

        // Update its properties to the passed in values.
        SetBranchProperties(properties, parentPath, owner, description);

        // Save the newly created branch object to the server
        sourceControl.CreateBranchObject(properties);
    }
}

private void SetBranchProperties(
    BranchProperties branchProperties,
    String parentPath, 
    String owner, 
    String description)
{
    // We don't want to overwrite the properties if the incoming values are null
    // so make sure to check the values of them before setting.
    if (parentPath != null)
    {
        branchProperties.ParentBranch = new ItemIdentifier(parentPath);
    }
    if (owner != null)
    {
        branchProperties.Owner = owner;
    }
    if (description != null)
    {
        branchProperties.Description = description;
    }
}

At this point we should be able to write a fairly simple outer loop that controls the calls to these methods.  This loop is going to consist of determining the proper parent branch, making sure the parent branch exists as a branch object and finally making sure the current branch exists as a branch object.  The reason we need to make sure the parent branch exists as a branch object is because a branch object cannot have a parent that is not also a branch object.  Here we go:

foreach (BranchSpec branchSpec in branchSpecs)
{
    String parentPath = branchSpec.OverrideParentPath;
    if (String.IsNullOrEmpty(parentPath))
    {
        parentPath = DetermineParentBranchPath(sourceControl, branchSpec);
    }

    if (!String.IsNullOrEmpty(parentPath))
    {
        EnsureBranchObjectExists(sourceControl, parentPath, null, null, null); 
    }
    EnsureBranchObjectExists(sourceControl, branchSpec.Path, parentPath, branchSpec.Owner, branchSpec.Description);
}

Note, that by passing nulls for the metadata for the parent branch object we will never overwrite valid metadata for that branch object because of the way we have written our SetBranchProperties method. 

And that should be all that it takes!  Once you run the code you should have all of your branches converted to branch objects within TFS.  Have fun with all of the cool visualizations!

First of all, if you are new to the TFS 2010 OM you may want to start with this post which introduces the TfsConnection, TfsConfigurationServer and TfsTeamProjectCollection objects.  Secondly, if you have not used TFS Impersonation before you will surely find it useful to read up on its introductory post here.

In order to use the code from the examples in this post you will need the following include statements:

using System;
using System.IO;
using Microsoft.TeamFoundation.Client;
using Microsoft.TeamFoundation.Framework.Client;
using Microsoft.TeamFoundation.Framework.Common;
using Microsoft.TeamFoundation.VersionControl.Client;

Let’s start by defining a scenario that we want to solve with this example.  Since we want to use TFS Impersonation along with the version control client OM a scenario that seems to work well would be one in which a service or a job checks in edits to a file on behalf of a user that triggers some event.  In order to have some data for our example to process, let’s define some variables up front.  This, of course, would need to come from some type of configuration file or user input if this example were to be turned into production code.

// Holds the uri that points to the team project collection we will communicate with. 
Uri uriToTeamProjectCollection;

// The account name of the user we will be performing this check in on behalf of. 
String userAccountName;

// The server path of the file in TFS that we will be modifying. 
String serverPathForFile;

// The place on the local file system where we want to download the file from TFS 
String localWorkspacePathForFile;

// Let's assume for this example that the file actually already exists on disk in the form that 
// we want to send it to the server as. That is, we want to copy the contents of this file
 // to send to the server. This is just our way of making changes to the file. 
String localCopyOfFile;

Since I wrote the majority of the TFS Impersonation code and haven’t touched the version control client OM before, let’s start with the easy stuff first :).  As you know from reading the TFS Impersonation post above we will actually have to make two connections to our collection in order to perform this scenario.  We will use the first connection to determine the IdentityDescriptor for the user we will be impersonating since that is the piece of information needed to perform impersonation:

TfsTeamProjectCollection baseUserTpcConnection = 
  new TfsTeamProjectCollection(uriToTeamProjectCollection);
IIdentityManagementService ims =
  baseUserTpcConnection.GetService<IIdentityManagementService>();

// Read out the identity of the user we want to impersonate 
TeamFoundationIdentity identity = ims.ReadIdentity(IdentitySearchFactor.AccountName, 
    userAccountName, MembershipQuery.None, ReadIdentityOptions.None);

Now that we have the identity of the user that we want to impersonate the next step is to actually create the impersonated connection to the collection.  But wait! This is a great time to remember that in order for impersonation to work, the user that the process is running as must have the “Make requests on behalf of others” permission for this collection.  If the user does not have this permission then you are going to see an Access Denied error message.  So, now that that is taken care of, let’s actually create the impersonated connection to the collection.

TfsTeamProjectCollection impersonatedTpcConnection = 
    new TfsTeamProjectCollection(uriToTeamProjectCollection, identity.Descriptor);

Great! So now we have our impersonated connection.  The next step is to check in the changes to a file using this impersonated connection.  In order to this, we must start by creating a workspace and setting up working folder mappings so that we can download the existing file on the server.  Note, that for any of you out there wondering, the following code would work in a non-impersonation scenario as well.

VersionControlServer sourceControl =
   impersonatedTpcConnection.GetService<VersionControlServer>();

// Create the workspace 
Workspace workspace =
   sourceControl.CreateWorkspace(String.Format("MyTempWorkspace-{0}", 
   DateTime.Now));

// Map the file that we want to change 
workspace.CreateMapping(new WorkingFolder(serverPathForFile, 
    localWorkspacePathForFile));

In the above code, we get the VersionControlServer object because it is the source for performing all version control operations.  Next, I create a workspace with a name that has a the current time included in it.  The reason that I use a time stamp within the name is because the name of a workspace for a given computer must be unique and although we will try to clean up this workspace later, we do not want a crash of the program to cause us to fail when trying to create the next workspace due to a naming conflict.  Finally, we map the server path for the file to a local path.  If you are going to change multiple files you do not need to create multiple mappings but can instead pick a root folder that both of the files live in.

The next thing we need to do is actually download the file that exists on the TFS server.  In our case, this is a simple as just calling the following method:

// Download the file 
workspace.Get();

Now that we have the file downloaded locally we could add an optimization that terminates execution if the file that we want to upload is the same as the existing file.  For brevity, I will avoid that optimization and leave that to you if you feel that you need it.  Thus, the next step is to pend the edit that we want to make and then copy in the contents of the file to the file that is mapped in the workspace:

// Pend the edit on the file to remove the read-only bit 
workspace.PendEdit(serverPathForFile);

// Copy our file to the mapped location 
File.Copy(localCopyOfFile, localWorkspacePathForFile, true);

Note that in the PendEdit call, I could have passed either the server path or the local path.

Finally, all we have left to do is check in the changes that we have pended and clean up our workspace.  This can be done via the following two calls:

// CheckIn the file 
workspace.CheckIn(new WorkspaceCheckInParameters(
    workspace.GetPendingChangesEnumerable(), 
    "Comment detailing what happened."));

// Clean up the workspace 
workspace.Delete();

And voila!  The changes to the file are now on the server and they will be recorded as if the impersonated user had performed the operation.  Also, it is good to know that if you didn’t implement the optimization of checking if the files and they happen to be the same then no check in will actually happen.

Hopefully that gives you a better understanding of both how TFS Impersonation works and how the version control client OM works.  Please send me any questions you have either via the contact link above or the comment section below.

Happy Coding!

In order to understand why we made this choice you should first understand how the Team Foundation Server architecture has changed for TFS 2010.  Your best bet is to read Brian Harry’s blog post on that topic and to focus on the section about Team Project Collections.  If you have used the TFS 2010 Beta 1 or Beta 2 APIs then it will be useful to read Grant Holliday’s blog post on the API renaming that we did.

Disclaimer: These classes were introduced in the RC version of TFS 2010.  If you are using one of the Beta versions of TFS 2010 you will not see these classes.

In order to use the code from the examples in this post you will need the following include statements:

using System;
using System.Collections.Generic;
using System.Collections.ObjectModel;
using Microsoft.TeamFoundation.Client;
using Microsoft.TeamFoundation.Framework.Client;
using Microsoft.TeamFoundation.Framework.Common;
using Microsoft.TeamFoundation.Common;

The TfsConnection Class

The TfsConnection class is the abstract base class for the TfsConfigurationServer and TfsTeamProjectCollection objects.  Before we talk about when you should use each derived class let’s discuss the shared functionality that exists in their base class.  Just like the TeamFoundationServer class in the TFS 2008 OM, the TfsConnection object aims to provide you various information about your connection with TFS as well as ways to initiate and control that connection.  If it isn’t explicitly mentioned here, the functions and properties that existed on the TeamFoundationServer object will likely exist in the same way on the TfsConnection object.

Identity Management

By integrating with the new IIdentityManagementService, the TfsConnection object is able to give you a much richer experience around dealing with the identities that are involved in the connection with TFS.  On the old TeamFoundationServer object you probably remember the three properties that reported the user you were connected as, they were:

public string AuthenticatedUserDisplayName { get; }
public Identity AuthenticatedUserIdentity { get; }
public string AuthenticatedUserName { get; }

Off of the new TfsConnection object you will find that this information along with other information is now available from this property:

public TeamFoundationIdentity AuthorizedIdentity { get; }

You may also notice that the prefix of the property has changed from “Authenticated” to “Authorized”.  This has to do with the new TFS Impersonation feature that is usable with all TfsConnection objects.  Check out the blog post in the link for more information.  Once you have done that then hopefully you will find the new constructor overloads and this function more useful:

public void GetAuthenticatedIdentity(out TeamFoundationIdentity identity);

Authentication

With the TeamFoundationServer object, getting the above user information always resulted in two server calls: one to actually authenticate with the server and the second to look information about the user you were connecting as.  In some cases, a third call was then made to read down location information so that other services (such as version control) could be used.  Fortunately, with the TfsConnection object, all of that information is now retrievable in a single call to the server via this method:

public void Connect(ConnectOptions connectOptions);

Catalog Integration

If you are new to TFS 2010 then the catalog service is likely new to you as well.  Check out this blog post to learn some more about the catalog service.  The TfsConnection object integrates with the catalog service to easily make its CatalogNode object available to the consumer via this property:

public abstract CatalogNode CatalogNode { get; }

This property will have different meaning based on whether the derived class is a TfsConfigurationServer or a TfsTeamProjectCollection object.  In the case where it is a TfsConfigurationServer object, the catalog node returned will be the one that represents the TFS instance.  In the case where it is a TfsTeamProjectCollection object, the catalog node returned will be the one that represents the given team project collection.

The TfsConfigurationServer Class

As you read in Brian’s blog post, in TFS 2010 we have introduced a new level of granularity between a TFS instance and the team projects that it contains.  That new level of granularity is called a team project collection and it is used to encapsulate a collection of team projects within a TFS instance.  The container for the set of team project collections is known as the configuration server.  In order to communicate with the configuration server you would construct a TfsConfigurationServer object using either its factory:

TfsConfigurationServer configurationServer = 
    TfsConfigurationServerFactory.GetConfigurationServer(new Uri("http://server:8080/tfs"));

or one of its constructors:

TfsConfigurationServer configurationServer = new TfsConfigurationServer(new Uri("http://server:8080/tfs"));

Of course, using the constructor will always create a new instance of the class while the factory will always give out the same instance of the class.  With this object you can now perform many actions against the configuration server.  Here is a (not necessarily exhaustive) list of services that you can get via the GetService<T>() call along with the tasks that they enable:

• Microsoft.TeamFoundation.Framework.Client.ITeamFoundationRegistry: Exposes APIs for viewing and managing the contents of the TFS registry at the configuration server level.
• Microsoft.TeamFoundation.Framework.Client.IIdentityManagementService: Exposes APIs for viewing and managing identities that exist in TFS and their group membership details at the configuration server level.
• Microsoft.TeamFoundation.Framework.Client.ITeamFoundationJobService: Exposes APIs for viewing and managing job definitions, job schedules and job run history at the configuration server level.
• Microsoft.TeamFoundation.Framework.Client.IPropertyService: Exposes APIs for reading from and writing to the generic property store at the configuration server level.
• Microsoft.TeamFoundation.Framework.Client.IEventService: Exposes APIs for viewing and managing event subscriptions at the configuration server level.
• Microsoft.TeamFoundation.Framework.Client.ISecurityService: Exposes APIs for viewing and managing security namespaces and the security data that each of those namespaces contain at the configuration server level.
• Microsoft.TeamFoundation.Framework.Client.ILocationService: Exposes APIs for viewing and managing the services defined at the configuration service level along with their configured locations.
• Microsoft.TeamFoundation.Client.TswaClientHyperlinkService: Exposes APIs for constructing URLs that communicate with TSWA.
• Microsoft.TeamFoundation.Framework.Client.ITeamProjectCollectionService: Exposes APIs that allow you to perform management and servicing tasks on the set of team project collections.
• Microsoft.TeamFoundation.Framework.Client.IAdministrationService: Exposes APIs for querying and canceling the active requests on the server.
• Microsoft.TeamFoundation.Framework.Client.ICatalogService: Exposes APIs for viewing and managing the contents of the catalog.
• Microsoft.TeamFoundation.Lab.Client.LabFrameworkService: Exposes APIs that allow you to perform verification of Lab Management objects during configuration.

One other thing you may want to do from your configuration server object is communicate with each of the team project collections that are members of this configuration server.  As we will discuss in the next section, all communication with a team project collection starts with the TfsTeamProjectCollection class.  In order to get the TfsTeamProjectCollection instance for a given team project collection you can call the following helper method from the TfsConfigurationServer class:

public TfsTeamProjectCollection GetTeamProjectCollection(Guid collectionId);

One way you could possibly use this method is to enumerate the team project collections that you can see using the catalog to get each of their IDs and then use this function to construct the proxy for talking to that team project collection.  Here is an example of how that would be done. (Note, if you want a better understand of how the catalog is being used here, check out my blog post on enumerating the team project collections using the catalog).

Uri configurationServerUri = new Uri("http://server:8080/tfs");
TfsConfigurationServer configurationServer =
        TfsConfigurationServerFactory.GetConfigurationServer(configurationServerUri);

CatalogNode configurationServerNode = configurationServer.CatalogNode;

// Query the children of the configuration server node for all of the team project collection nodes
ReadOnlyCollection<CatalogNode> tpcNodes = configurationServerNode.QueryChildren(
        new Guid[] { CatalogResourceTypes.ProjectCollection }, 
        false,                                                 
        CatalogQueryOptions.None);

foreach (CatalogNode tpcNode in tpcNodes)
{
    Guid tpcId = new Guid(tpcNode.Resource.Properties["InstanceId"]);
    TfsTeamProjectCollection tpc = configurationServer.GetTeamProjectCollection(tpcId);

    // Do your tpc work here.
}

So, now that you know how to get a TfsTeamProjectCollection class, let’s discuss that further.

The TfsTeamProjectCollection Class

From reading the topic above, you already know that you can get an instance of a TfsTeamProjectCollection class from its related TfsConfigurationServer object.  Of course, you can also create an object using the factory method:

TfsTeamProjectCollection tpc = 
    TfsTeamProjectCollectionFactory.GetTeamProjectCollection(new Uri("http://server:8080/tfs/Collection"));

or from one of its constructors:

TfsTeamProjectCollection tpc = new TfsTeamProjectCollection(new Uri("http://server:8080/tfs/Collection"));

Out of the three classes presented in this blog post, this class is the most like the old TeamFoundationServer object because of the services you can get from it.  Just like the old TeamFoundationServer object, this class provides the capability for talking to the version control, work item tracking and build services as well as all of the other services that you used in the TFS 2005 and 2008 to work with your team projects.  Because of this, you can use the TfsTeamProjectCollection class to talk to TFS 2010 team project collections as well as 2008 and 2005 instances of Team Foundation Server.

Speaking of the services that you can get from the TfsTeamProjectCollection.GetService<>() method, let’s take a look at another (not necessarily exhaustive) list of services that TFS ships with:

• Microsoft.TeamFoundation.Framework.Client.ITeamFoundationRegistry: Exposes APIs for viewing and managing the contents of the TFS registry for this team project collection.
• Microsoft.TeamFoundation.Framework.Client.IIdentityManagementService: Exposes APIs for viewing and managing identities that exist in TFS and their group membership details for this team project collection.
• Microsoft.TeamFoundation.Framework.Client.ITeamFoundationJobService: Exposes APIs for viewing and managing job definitions, job schedules and job run history for this team project collection.
• Microsoft.TeamFoundation.Framework.Client.IPropertyService: Exposes APIs for reading from and writing to the generic property store within this team project collection.
• Microsoft.TeamFoundation.Framework.Client.IEventService: Exposes APIs for viewing and managing event subscriptions for this team project collection.
• Microsoft.TeamFoundation.Framework.Client.ISecurityService: Exposes APIs for viewing and managing security namespaces and the security data that each of those namespaces contain for this team project collection.
• Microsoft.TeamFoundation.Framework.Client.ILocationService: Exposes APIs for viewing and managing the services defined for this team project collection along with their configured locations.
• Microsoft.TeamFoundation.Client.TswaClientHyperlinkService: Exposes APIs for constructing URLs that communicate with TSWA.
• Microsoft.TeamFoundation.VersionControl.Client.VersionControlServer: Exposes APIs for performing all version control related operations.
• Microsoft.TeamFoundation.Build.Client.IBuildServer: Exposes APIs for viewing and managing build controllers, build agents, build definitions, build results and the build queue.
• Microsoft.TeamFoundation.WorkItemTracking.Client.WorkItemStore: Exposes APIs for performing all work item tracking related operations.
• Microsoft.TeamFoundation.TestManagement.Client.ITestManagementService: Exposes APIs for viewing and managing test controllers, test runs and test results.
• Microsoft.TeamFoundation.Lab.Client.LabFrameworkService: Exposes APIs that allow you to perform verification of Lab Management objects during configuration.
• Microsoft.TeamFoundation.Lab.Client.LabAdminService: Exposes APIs for viewing and managing the top-level lab management objects.
• Microsoft.TeamFoundation.Lab.Client.LabService: Exposes APIs for viewing and managing other lab management objects.
• Microsoft.TeamFoundation.Lab.WorkflowIntegration.Client.IWorkflowIntegrationService: Exposes APIs for viewing and managing workflow integration for lab environments that are created by the Team Foundation Lab Service.
• Microsoft.TeamFoundation.Lab.TestIntegration.Client.ITestIntegrationService: Exposes APIs for viewing and managing the testing capability with lab environments that are created by the Team Foundation Lab Service.
• Microsoft.TeamFoundation.ILinking: Exposes APIs for the retrieving the details about linking artifacts and their URLs.
• Microsoft.TeamFoundation.Server.ICommonStructureService3: Exposes APIs for viewing and managing areas, iterations, and team projects.
• Microsoft.TeamFoundation.Server.IServerStatus: Exposes APIs for getting the status of the server.
• Microsoft.TeamFoundation.Server.IProcessTemplates: Exposes APIs for viewing and managing the process templates for this team project collection.

There are also some services that can still be retrieved using GetService<T>() because of backwards compatibility reasons but have replaced by newer services.  Here are a list of those with the service(s) they have been replaced by.

• Microsoft.TeamFoundation.Server.IRegistration: This has been replaced by the ILocationService and ITeamFoundationRegistry services from above.
• Microsoft.TeamFoundation.Server.ICommonStructureService: This has been replaced by the ICommonStructureService3 service from above.
• Microsoft.TeamFoundation.Server.IGroupSecurityService: This has been replaced by the IIdentityManagementService from above.
• Microsoft.TeamFoundation.Server.IGroupSecurityService2: This has been replaced by the IIdentityManagementService from above.
• Microsoft.TeamFoundation.Server.IAuthorizationService: This has been replaced by the ISecurityService from above.

Also, just as the TfsConfigurationServer class has a helper method for retrieving TfsTeamProjectCollection objects, the TfsTeamProjectCollection class has a property for retrieving the TfsConfigurationServer object that it is a member of:

public TfsConfigurationServer ConfigurationServer { get; }

I notice that some services can be retrieved from both TfsConfigurationServer and TfsTeamProjectCollection instances.  Why is this and how are they different?

Great observation.  The services that are available from both of these objects are known as “framework” services.  From the list above you can see that the ITeamFoundationRegistry, IIdentityManagementService, ITeamFoundationJobService, IPropertyService, IEventService, ISecurityService and ILocationService are all framework services.  Whether you get these services from a TfsConfigurationServer or TfsTeamProjectCollection object, they will still provide the same functionality but the scope that you are affecting with those methods will be different.

Let’s look at the ISecurityService to demonstrate this.  One of the functions this service provides is the ability to list all of the security namespaces that exist for that host.  If you list the security namespaces for a security service that was retrieved from a TfsTeamProjectCollection object then you will see a security namespace for version control because we apply security to version controlled items within a team project collection.  However, you would not see this security namespace exist for a security service retrieved from a TfsConfigurationServer object because version control does not exist within the configuration server.  The opposite is true for the team project collection management security namespace.  This namespace will only exist for a security service retrieved from a TfsConfigurationServer object because it offers functionality for managing team project collections.

The same is true for all of the other framework services.  If you set a registry entry using the ITeamFoundationRegistry service from a TfsTeamProjectCollection object, it will not have any affect on the ITeamFoundationRegistry service from the TfsConfigurationServer object.  The same is also true for TfsTeamProjectCollection objects that talk to two different team project collections.  Setting a security or registry entry against on team project collection will not affect the security or registry setting in a different team project collection object.

Hopefully this gives you a good jumping off point for utilizing these new classes.  Feel free to hit up the comment section below or the contact link above if you have any questions.

Recently, while dogfooding our internal pioneer server, a few members of our team started to notice this error message when downloading files from TFS:

C:\dev\code\somefile.txt: Unable to read data from the transport connection: An existing connection was forcibly closed by the remote host.

Luckily, we were able to reproduce the issue on a consistent enough basis to investigate the issue.  After a few fun days of client-side TFS logging, sever-side TFS logging, TFS activity logging, fiddler tracing, netmon tracing, procmon tracing and finally http.sys tracing we were able to determine that we were being affected by an http.sys bug that was introduced in Windows Server 2008 R2.

Are you experiencing the same issue that we were?

Let’s find out.  First of all, this bug is new to Windows Server 2008 R2.  If you are running any version of Windows Server 2003, Windows Server 2008 R1 RTM or Windows Server 2008 R1 SP1 then you are most likely not hitting the same bug that we were.  The issue tended to occur more often if the file that was being downloaded was relatively large (> 2MB) and rate of occurrence seemed to grow with the size of the file.  Finally, we were only able to reproduce the issue over slower networks (3 to 4 kb/sec file transfer rate). 

Great news! The bug has been fixed!

This bug has been fixed by the Windows team and they have released a QFE for it.  You can find the QFE here.  You will need to install in on all of your ATs.

The following lists the initial workarounds that we were able to come up with before this bug was fixed.  I am going to leave them up here for reference but the real solution should be to install the QFE mentioned above.

--

In order to lower the threshold follow these directions:

1. Open the IIS Manager
2. In the Connections pane, make sure the name of your AT is selected.
3. In the middle pane (titled “<MachineName> Home”), make sure you are in the “Features View” (bottom) and scroll down to the Management section.
4. Double-click the “Configuration Editor” icon.
5. The middle pane should now have the title “Configuration Editor”.  In the Section pull down near the top, expand the system.applicationHost and select “webLimits”.
6. You should now see a bunch of property value pairs, one of which is named “minBytesPerSecond”.  Its value is most like 240.  You will want to lower this value for the workaround. 

In general, the lower the threshold is, the lower the chances are that you hit the issue above.  However, you may not want to lower the setting too much because then connections that should be killed by this timer will not be appropriately cleaned up.  Play around with values to see what works best for you.

If you have any other questions, be sure to let us know.

For those of you new to TFS 2010, the pane on the left above shows the list of “Team Project Collections” that exist on the TFS Instance that you have connected to.  If you want a deeper explanation of what a team project collection is then check out Brian Harry’s post on the subject.  Recently, a few people have asked what the proper way is to retrieve that list of team project collections using the TFS 2010 client APIs so I figured it was worth a blog post since this seems to be a fairly popular question.

Disclaimer: The code presented in this blog post assumes you are using the RTM version of TFS.  Some of these APIs were refactored between TFS 2010 Beta 2 and TFS 2010 RTM.  Please see the section at the end of the post to see how the new API names map to those in the Beta 1 and Beta 2 versions of TFS 2010.

If you are new to the TFS 2010 OM you may want to start with this post which introduces the TfsConnection, TfsConfigurationServer and TfsTeamProjectCollection objects.

In order to use the code from the examples in this post you will need the following include statements:

using System;
using System.Collections.Generic;
using System.Collections.ObjectModel;
using Microsoft.TeamFoundation.Client;
using Microsoft.TeamFoundation.Framework.Client;
using Microsoft.TeamFoundation.Framework.Common;

First, let’s talk about how not to get this list of team project collections.

So, if you are at home (or at work) digging through the new TFS 2010 APIs trying to find out where to get the list of team project collections you may come across the new TeamProjectCollectionService, seen that it has a GetCollections method and think “Great! I have found what I am looking for”.  Unfortunately, this is not the case.  The TeamProjectCollectionService can be thought of more as a management related service than a user related service.  It offers methods to create, delete and edit team project collections.  While it also does offer the previously mentioned method to get the list of team project collections, the data returned by that function call has too much information for the normal user to see.  For example, it contains the connection string to the database that stores the data for each team project collection and exposing this information to a normal user is not acceptable.

While we are on the topic though, if you are writing a management tool, here is how you would use the TeamProjectCollectionService to get a list of team project collections along with some of their configuration details:

Uri configurationServerUri = new Uri("http://your-server:8080/tfs");
TfsConfigurationServer configurationServer = 
        TfsConfigurationServerFactory.GetConfigurationServer(configurationServerUri);

ITeamProjectCollectionService tpcService = configurationServer.GetService<ITeamProjectCollectionService>();

foreach (TeamProjectCollection tpc in tpcService.GetCollections())
{
    // Do your work for each TeamProjectCollection object here.
}

The GetCollections() method called here is guarded by the “Edit server-level information” permission which by default is only granted to server administrators.  That means, if a regular user were to call this method then that user would see the message:

“Access Denied: DOMAIN\NormalUser needs the following permission(s) to perform this action: Edit instance-level information”

So, what is the proper way to get the list of team project collections for a normal user then?

The answer to that question relies on a new technology introduced in TFS 2010 called the catalog service.  The goal of the new catalog service is to provide a publishing and discovery service for any resources used in a TFS deployment.  For example, team project collections, team projects, SharePoint resources and Reporting Service resources among many other things are represented in the catalog.  In order to represent such diverse objects and the relationships between them in a single store the catalog has many different concepts, some of which are fairly complicated.  I am planning an in-depth look at the catalog for a future post so for the purpose of this discussion we will try to stay on the surface.

Each entity that is represented in the catalog exists as a CatalogResource.  Each CatalogResource has a type (team project collection, team project, etc.) and some properties that better define the object that it represents.  The catalog stores how each CatalogResource relates to other CatalogResources in a hierarchical fashion.  Currently the catalog has two well-defined trees for representing relationships: the Infrastructure tree and the Organizational tree.  The Infrastructure tree is used to represent the hardware in your TFS deployment and can answer queries like “show me all of the machines that I have TFS Web Applications installed on”.  The Organizational tree is used to represent the relationships between the TFS resources such as the team project collections and team projects in your deployment. 

In order to be represented in one of the catalog trees mentioned above a CatalogResource must be associated with a CatalogNode.  A CatalogNode represents a place in the catalog tree and thus conveys how each resource relates to each other.  For example, there is a CatalogResource for the TFS configuration server associated with a CatalogNode under the root of the Organizational tree.  As children of the configuration server node, there is a CatalogNode associated with each of the CatalogResources that represent team project collections.  Continuing, there is a CatalogNode associated with each of the CatalogResources that represent a team project under the given team project collection node that that team project belongs to.  Hopefully with that background information, the following example on retrieving the list of team project collections from the catalog will make sense:

Uri configurationServerUri = new Uri("http://your-server:8080/tfs");
TfsConfigurationServer configurationServer =
        TfsConfigurationServerFactory.GetConfigurationServer(configurationServerUri);

CatalogNode configurationServerNode = configurationServer.CatalogNode;

// Query the children of the configuration server node for all of the team project collection nodes
ReadOnlyCollection<CatalogNode> tpcNodes = configurationServerNode.QueryChildren(
        new Guid[] { CatalogResourceTypes.ProjectCollection }, 
        false,                                                 
        CatalogQueryOptions.None);

foreach (CatalogNode tpcNode in tpcNodes)
{
    // Use tpcNode.Resource to get the details for each team project collection.
}

Let’s go into this example with a little more detail now.  The CatalogNode for any TfsConnection object is stored as a property called “CatalogNode”.  From this we can call the QueryChildren method to find out information about what children it has.  In the first argument to this call we specify that we only want to see children that are of type “ProjectCollection”.  In the second argument, we specify the value “false” for recurse since we know that a team project collection node will only exist as a child of our node.  If it were possible that a team project collection node could exist as a grandchild (or deeper) of our node then we would need to pass true here.  Finally, we pass CatalogQueryOptions.None as the last parameter because we don’t need any details about the parent nodes or dependencies filled out.  Don’t worry about dependencies for now, those will be covered in a later post.  So, with that query, you now have a list of all of the catalog nodes that represent team project collections that you are allowed to see.

Great, so what exactly can I learn or do with these CatalogResource objects that represent the team project collections?

Good question.  For starters, accessing the following properties will give you relevant information about the team project collection:

// Get the team project collection name.
String displayName = tpcNode.Resource.DisplayName;

// Get the team project collection description.
String description = tpcNode.Resource.Description;

// Get other dynamic properties that describe this collection
foreach (KeyValuePair<String, String> property in tpcNode.Resource.Properties)
{
    String propertyKey = property.Key;
    String propertyValue = property.Value;
}

Also, using the information in the ServiceReferences property you can get the url that is used to actually connect to the team project collection:

// Get the ServiceDefinition for the team project collection from the resource.
ServiceDefinition tpcServiceDefinition = tpcNode.Resource.ServiceReferences["Location"];

ILocationService configLocationService = configurationServer.GetService<ILocationService>();
Uri tpcUri = new Uri(configLocationService.LocationForCurrentConnection(tpcServiceDefinition));

// Actually connect to the team project collection
TfsTeamProjectCollection tpc = TfsTeamProjectCollectionFactory.GetTeamProjectCollection(tpcUri);

// Perform operations against the team project collection object here

Hopefully that should be enough of an example to get you started with working with the catalog to determine the list of team project collections.

Cool, anything else I should know about using the catalog service?

I will dive deeper into the catalog service at a later point but here is a good tip: the catalog service is not backward compatible and will not work against a TFS 2005 or TFS 2008 server.  In order to determine if you are talking to a TFS 2010 server from your client application, check out this post.  If there is anything specific that you would like to know about the catalog service, feel free to mention it in the comments or shoot me an email and I will make sure to address it.

If you are using TFS 2010 Beta 1 or Beta 2 then everything you just read is still true but some of the APIs have different names.  Here are the mappings that you will need to make this work in one of the betas:

TfsTeamProjectCollection is equivalent to TeamFoundationServer.  TfsConfigurationServer is equivalent to TeamFoundationApplicationInstance.  TfsConnection is equivalent to TeamFoundationServerBase.  For more information on this see Grant Holliday's blog post.

The issue that inspired this post happened a few days ago.  A fellow developer had reported that one of my stored procedures seemed to “hang” while performing an operation so I needed to dig in to hopefully determine what the issue was.  Since I wasn’t able to repro the issue with a simple case my next plan was to try to capture the exact command that caused the issue to reproduce using SQL Server Profiler and then replay that command in Sql Server Management Studio repeatedly with a bunch of different traces turned on.

While I was in the process of capturing the command using the profiling tool I noticed that the operation appeared to be in this “hanging” state that my colleague had reported.  Since I had assumed that the hang was due to a bad SQL query plan or some other intermittent problem I was ecstatic that I was able to get it to reproduce.  Then the panic set in.  I realized that I didn’t have any statement level traces set up and was immediately worried that I wouldn’t gain any knowledge from this instance of a seemingly hard-to-reproduce issue.

So, with time on this repro running low, I did what every developer on my team with a SQL emergency would do, and that was to call my co-worker Chandru to help.  Luckily, Chandru was able to save the day and determine what statement was causing the delay within the stored procedure before we lost the repro.  So, for both your benefit and mine here is a recap of what I learned about how he was able to figure this out:

On to the contrived example!

In order to reproduce this issue at home, let’s use this example stored procedure:

CREATE PROCEDURE prc_LongRunningProcedure
AS

-- Declare some table
DECLARE @table TABLE (
    Value1  INT,
    Value2  INT
)

INSERT  @table (Value1, Value2)
VALUES  (
        1,
        2
        )
        
WAITFOR DELAY '05:00'

SELECT  *
FROM    @table

RETURN 0
GO

After a quick inspection you will notice that the above procedure declares a temporary table, inserts some values, waits for 5 hours, and then returns the values from the table.  While this example is incredibly contrived it will serve our purposes well.  In an SSMS query window copy in the statement above and run it to create the stored procedure in a test database.  Next, in another query window, run the following statement:

EXEC dbo.prc_LongRunningProcedure

So now we have achieved the same issue that I was experiencing: a long running stored procedure that was stuck on an unknown statement.  Okay, maybe you can guess what statement we are stuck on here but you know what I mean.

So, what next?

Luckily, SQL provides a number of different tables and functions that help track things that are of interest to someone trying to debug various issues.  One of the most commonly useful tables is sys.dm_exec_requests which will report some details about the currently operating requests.  Access those details using the following query:

SELECT  *
FROM    sys.dm_exec_requests requests
WHERE   requests.session_id > 50
ORDER BY total_elapsed_time DESC

Note that we make sure to only select requests with a session_id above 50 because these represent “user” requests.  Any request with a session_id at or below 50 represents a “system” request and those won’t be useful to us here.  Running this statement in a new query editor window in SSMS yielded the following results for me.  Note, you may see more or less results with different ids when you run this against your server.

Scrolling to the right it is fairly obvious for me which request is the long running one: the top row has a much higher total_elapsed_time value than the other entries.  However, in a real world scenario, you may not be able to tell what stored procedure is running.  In order to associate the currently running request with the stored procedure that is running we will have to call upon sys.dm_exec_sql_text:

SELECT  requests.session_id, 
        requests.status, 
        requests.command, 
        requests.statement_start_offset,
        requests.statement_end_offset,
        requests.total_elapsed_time,
        details.text
FROM    sys.dm_exec_requests requests
CROSS APPLY sys.dm_exec_sql_text (requests.plan_handle) details
WHERE   requests.session_id > 50
ORDER BY total_elapsed_time DESC

This statement uses the plan handle from the requests table to call the table-valued function sys.dm_exec_sql_text to determine the text of the procedure that is being run.  When I run the above query, I see this:

In case we weren’t sure what row was ours before we can tell now because the details.text column shows the text from our example stored procedure.  Let’s talk about some other details in this output.  The status column will tell you the current status of the request.  Since we used the WAITFOR command to cause our program to freeze we see that the status is “suspended”.  If this were an actual stored procedure you may see “running” here if a statement is currently executing or “suspended” if you are waiting on something (like a lock resource).  For information on other values, check out this doc page.

Another useful piece of information is the command column.  It will tell you what type of command is currently running.  Again, in our case, the WAITFOR command pollutes this field but in a real world scenario this would tell you something such as “DELETE” or “INSERT” which can help you determine your problem area.  At this point, if you still don’t know what statement the delay is caused by we can dig a little deeper with the information provided by sys.dm_exec_requests and sys.dm_exec_sql_text:

SELECT  SUBSTRING(detail.text, 
                  requests.statement_start_offset / 2, 
                  (requests.statement_end_offset - requests.statement_start_offset) / 2)
FROM    sys.dm_exec_requests requests
CROSS APPLY sys.dm_exec_sql_text (requests.plan_handle) detail
WHERE   requests.session_id = 67

Here, we do the same CROSS APPLY as before but we are more selective and only look at the row that interests us (it has session_id 67).  Also, instead of looking at the entire sql text, we use the statement offsets provided by sys.dm_exec_requests to find the exact statement that is currently executing:

So, at this point, we know both the stored procedure and the statement that was executing when the delay was noticed.  Now, as far as figuring out what the delay is caused by, that one is on you :).

Disclaimer: The code presented in this blog post assumes you are using the RTM version of TFS.  Some of these APIs were refactored between TFS 2010 Beta 2 and TFS 2010 RTM.  Please see the section at the end of the post to see how the new API names map to those in the Beta 1 and Beta 2 versions of TFS 2010.

If you are new to the TFS 2010 OM you may want to start with this post which introduces the TfsConnection, TfsConfigurationServer and TfsTeamProjectCollection objects.

In order to use the code from the examples in this post you will need the following include statements:

using System;
using System.Collections.Generic;
using Microsoft.TeamFoundation;
using Microsoft.TeamFoundation.Client;
using Microsoft.TeamFoundation.Framework.Client;
using Microsoft.TeamFoundation.Server;

What Services Does this Instance of TFS Offer?

Included in the release of Microsoft Team Foundation Server 2010 there are a number of new services that exist that provide a great deal of new functionality.  Unfortunately, for a client application developer, in order to take advantage of some of these new features the client must first determine if the given TFS server supports these new features.

It seems that one way to accomplish this would be to maintain a list of what features are shipped in each version of TFS, determine which version of TFS is being talked to and then make assumptions about what services can be called.  Firstly, this method seems a bit clunky and has a lot of overhead.  Where are you going to find a list of all of the services that each version of TFS offers?  How are you going to represent these in your codebase?  And most importantly, how will your support forward compatibility with future TFS versions if you don’t know what services they will or will not offer?

Also, what about server-side third party add-ins for TFS?  How will you be able to tell if any of these exist if all you are doing is looking at some type of version stamp for the given server? 

The answer is that you won’t be able to do any of these things effectively by following this approach.  Instead of memorizing what services are available in each version of TFS it seems that what we really should be doing is asking this instance of TFS what services it offers.

So how do I ask a given instance of TFS what services it offers?

Fortunately, there is a TFS service for that!  Well, that is not its sole purpose of the service but the Team Foundation Server Location Service has the ability to tell the client what services are available from a given instance of TFS.  This is a new service that has been introduced in TFS 2010.

Wait, if it is a new service in TFS 2010 then how do I know if I can use it without checking to see if I am talking to a TFS 2010 server first?

Great question, I am glad to see you have been paying attention.  Fortunately, a few of the new services that we have introduced in TFS 2010 have backward compatibility built-in to parts of them and the location service is one of these services.  That means, whether you are talking to the 2005, 2008 or 2010 version of TFS you will be able to use certain functions from the location service.

Let’s start by seeing a code example of how you can retrieve the location service to start using it:

TfsTeamProjectCollection teamProjectCollection = 
        new TfsTeamProjectCollection(new Uri("http://your-server:8080/tfs/Collection0"));

ILocationService locationService = teamProjectCollection.GetService<ILocationService>();

Note, the location service is also available off of a TfsConfigurationServer object and can be used the same way we will use it in the following examples. 

Before we dig in on how you can use this object to determine if a given service is present we first need to get some background on what exactly the location service does.  I am planning a larger post at some point to provide an in-depth look at the functionality of the location service so I will keep this short.  For the purpose of this discussion, you can think of the location service as a means for the registration and discoverability of the services offered within a TFS instance.  In the location service, a service is defined by an object called a ServiceDefinition. 

The ServiceDefinition object contains many properties that convey the different attributes of a given service but for right now we will only worry about the ServiceType and Identifier properties.  Much like a .NET interface a service defines a collection of methods that serve as a contract between the user of the service and the implementer of the service.  This collection of methods is given a name, just as a .NET interface is given a name, and that name is what populates the ServiceType field.  Now, just as a .NET interface can have many different classes that implement it, the same is true for our ServiceType.  This means that multiple ServiceDefinitions can have the same ServiceType.  However, each different implementation of a given ServiceType will have its own unique Identifier (in the form of a GUID).

With that knowledge, hopefully the next sections will make sense. 

When coding it is generally useful to know if a specific service exists.  Let’s say that you want to take advantage of the new Team Foundation Server Security Service that has been introduced in TFS 2010 but you also want to fail gracefully if you are talking to a version of the server that doesn’t offer the new security service.  Moreover, let’s also assume that you want to work with the specific security service that TFS ships with.  In order to accomplish this your code could look like this:

if (null != locationService.LocationForCurrentConnection(ServiceInterfaces.SecurityService, 
                                                         FrameworkServiceIdentifiers.CollectionSecurity)) 
{ 
    DoSecurityServiceWork(); 
}
else
{
    ShowMessageThatSecurityServiceIsNotAvailableForThisServer();
}

This code is asking the location service if there is a known location for a service that fulfills the security service contract and has the well-known identifier that represents the TFS implementation of the security service.  If the location service returns an object that means the service is registered and if it returns null then it means that this service does not exist on the current server.  Each of the TFS Services has a well known ServiceType and a well-known Identifier that uniquely define and identify it.

Cool, so how expensive is it to ask the location service if a service is defined?  Does it make a server call each time?

The first time a call is made to the location service for a given host it will query that host for all of the services defined on it.  All of those services are then cached on the client and each subsequent call uses that cache to determine if the service is present or not.  Furthermore, this cache is persisted to disk so the next time this client application starts up it will not have to query the services again.  That means that unless we are talking about the first call to this location service then each call to look up a service is very inexpensive.

But what if I really, really just need to know what version of the server I am talking to?

Unfortunately there is not some uniform method that you can call that will simply tell you “You are communicating with version X of TFS”.  In order to determine what version of the server you are talking to we are going to use the principals about querying for services above along with some knowledge about what services were available in each release.

As mentioned above, the security service is new in TFS 2010.  We also know that version 2 of the group security service was introduced in TFS 2008.  With that information, we can use the following algorithm to determine which version of the server we are talking to:

if (null != locationService.LocationForCurrentConnection(ServiceInterfaces.SecurityService, 
                                                         FrameworkServiceIdentifiers.CollectionSecurity))
{
    //We are talking to TFS 2010
}
else if (null != locationService.LocationForCurrentConnection("GroupSecurity2", 
                                                              IntegrationServiceIdentifiers.GroupSecurity2))
{
    //We are talking to TFS 2008
}
else
{
    //We are talking to TFS 2005
}

Since we are talking about compatibility here what if I want to update my 2008 clients to be aware of what server version they are talking to.  I am guessing I cannot use the location service, correct?

Correct, the location service isn’t available in the TFS 2008 Client OM.  However, you can still accomplish this feat using the Team Foundation Server Registration Service – though the solution will be a bit more terse.  The registration service is basically a collection of objects called RegistrationEntry.  In TFS 2010 we added a new RegistrationEntry for the value “Framework”.  We will use this along with our other knowledge about version 2 of the group security service to build the following algorithm:

TeamFoundationServer server = new TeamFoundationServer("http://your-server:8080/");
IRegistration registrationService = (IRegistration)server.GetService(typeof(IRegistration));

RegistrationEntry[] frameworkEntries = registrationService.GetRegistrationEntries("Framework");
if (frameworkEntries.Length > 0)
{
    //We are talking to TFS 2010
}
else
{
    RegistrationEntry[] vstfsEntries = registrationService.GetRegistrationEntries("vstfs");
    if (vstfsEntries.Length != 1)
    {
        //We must be talking to an unknown version of TFS
    }
    else
    {
        Boolean groupSecurity2Found = false;
        foreach (ServiceInterface serviceInterface in vstfsEntries[0].ServiceInterfaces)
        {
            if (serviceInterface.Name.Equals("GroupSecurity2", StringComparison.OrdinalIgnoreCase))
            {
                groupSecurity2Found = true;
            }
        }

        if (groupSecurity2Found)
        {
            //We are talking to TFS 2008
        }
        else
        {
            //We are talking to TFS 2005
        }
    }
}

Hopefully that should be enough to get you started with using the location service to determine what services are available from the TFS Instance you are talking to.  Feel free to ask questions in the comments or contact me via the contact tab.

If you are using TFS 2010 Beta 1 or Beta 2 then everything you just read is still true but some of the APIs have different names.  Here are the mappings that you will need to make this work in one of the betas:

TfsTeamProjectCollection is equivalent to TeamFoundationServer.  For more information on this see Grant Holliday's blog post.

Also, in TFS 2010 Beta 2 the function LocationForCurrentConnection was named FindServiceLocation.

Disclaimer: The code presented in this blog post assumes you are using the RTM version of TFS.  These APIs were refactored between TFS 2010 Beta 2 and TFS 2010 RTM.  Please see the section at the end of the post to see how the new API names map to those in the Beta 1 and Beta 2 versions of TFS 2010.

If you are new to the TFS 2010 OM you may want to start with this post which introduces the TfsConnection, TfsConfigurationServer and TfsTeamProjectCollection objects.

What is TFS Impersonation?

TFS Impersonation is a feature that was introduced in TFS 2010 in order to allow a process running as User A to make web service calls to TFS in such a way that TFS thinks the actions are being performed by User B.

This is often useful when writing a tool or service that wants to perform actions in Team Foundation Server and have the server apply permissions and record the action as if a given user had performed it.  For the purposes of this blog post we will assume that this action is the queuing of a build on behalf of another user (perhaps in response to a notification that a CheckIn by this user has just occurred).

Isn’t this already possible through the use of Windows Impersonation?

Well, yes, that is true.  I assume you mean by doing something like this:

private void QueueBuildForUserUsingWindowsImpersonation(
    Uri teamProjectCollectionUri,
    String teamProjectName,
    String buildDefinitionName,
    String principal, 
    String authority, 
    String password)
{
    IntPtr impersonatedUserToken;
    LogonUser(principal, authority, password, LogonTypes.Interactive, 
            LogonProviders.Default, out impersonatedUserToken);

    WindowsIdentity identity = new WindowsIdentity(impersonatedUserToken);
    using (WindowsImpersonationContext impersonationContext = identity.Impersonate())
    {
        // Create the proxy object so that we can communicate with the Team Project Collection
        TfsTeamProjectCollection teamProjectCollection = 
                new TfsTeamProjectCollection(teamProjectCollectionUri);

        IBuildServer buildServer = teamProjectCollection.GetService<IBuildServer>();
        
        // Find the build definition for the build to queue.
        IBuildDefinition buildDefinition = GetBuildDefinition(buildServer, teamProjectName, 
                buildDefinitionName);

        if (buildDefinition == null)
        {
            WriteToLog("Couldn't find build definition");
            return;
        }
        else
        {
            WriteToLog("Found build definition, queuing now...");
        }

        // Queue the build as our impersonated user.
        buildServer.QueueBuild(buildDefinition.CreateBuildRequest());

        WriteToLog("Build successfully queued");
    }
}

Yes, the code above will in fact queue a build as the user who’s information is passed into the function (principal, authority and password) but this has some caveats. 

• First and foremost, you must have the user’s username and password in order to call LogonUser.  This data is usually only available through user input and in the case where your tool is automatically queuing builds after CheckIns, it is likely that you will not have this information or will have to do something unsafe to get access to it.
• This only works for windows identities on windows clients.  With Microsoft’s acquisition of the Teamprise Client Suite it is important that the TFS Client Object Model offers its own method of impersonation instead of relying on the operating system to support it and it is worthwhile to have one standard solution that applies across all operating systems.
• It means that you use the LogonUser unmanaged method which requires dll importing the advapi32.dll.  LogonUser can be slow, is easy to misuse and requires that you handle a series of error conditions (all of which are not done here).
• Finally, this also means that your current thread is running as the user that you have impersonated.  If the thread does logging (as above) or other actions that cause disk resources to be created, deleted or modified then the user that is being impersonated will need the appropriate permissions to these resources or methods of delaying these actions until the impersonation has ended will need to be implemented.

Well, what about supplying a different set of credentials to the TfsTeamProjectCollection object that you are creating?  Doesn’t that get around some of these problems and still accomplish the main goal?

Well, yes, supplying different credentials to the TfsTeamProjectCollection object will get you around a few of the above caveats.  Let’s look at an example of this:

private void QueueBuildForUserUsingDifferentCredentials(
    Uri teamProjectCollectionUri,
    String teamProjectName,
    String buildDefinitionName,
    String principal,
    String authority,
    String password)
{
    // Create the proxy object so that we can communicate with the Team Project Collection
    TfsTeamProjectCollection teamProjectCollection =
            new TfsTeamProjectCollection(teamProjectCollectionUri, 
                new NetworkCredential(principal, password, authority));

    IBuildServer buildServer = teamProjectCollection.GetService<IBuildServer>();

    // Find the build definition for the build to queue.
    IBuildDefinition buildDefinition = GetBuildDefinition(buildServer, teamProjectName,
            buildDefinitionName);

    if (buildDefinition == null)
    {
        WriteToLog("Couldn't find build definition");
        return;
    }
    else
    {
        WriteToLog("Found build definition, queuing now...");
    }

    // Queue the build as our impersonated user.
    buildServer.QueueBuild(buildDefinition.CreateBuildRequest());

    WriteToLog("Build successfully queued");
}

In this example we are able to stop using the clunky Windows Impersonation which saves us the use of unmanaged code and DllImports and also prevents the problems with logging mentioned above.  Also, since this is a wholly TFS solution, this solution can be used by Teamprise users as well. 

However, this solution still runs into the main problem that we had above which is that in order to create the NetworkCredential object for the other user that user’s password is needed. 

Ahh, gotcha.  So I am guessing this is where TFS Impersonation comes in?

Yes, this is where TFS Impersonation comes in.  The main advantages that TFS Impersonation has over the two solutions above is that it does not require that the user’s password is supplied.

Before we dive into the example, let’s look at the APIs that are related to TFS Impersonation.  Off of any object that derives from the TfsConnection object (currently only TfsTeamProjectCollection and TfsConfigurationServer) there are new constructors that take the IdentityDescriptor of the identity to impersonate:

public TfsTeamProjectCollection(
    Uri uri,
    IdentityDescriptor identityToImpersonate)

This method (and the other overloads that take the identityToImpersonate parameter) constructs an instance of the TfsTeamProjectCollection object that will make all web requests as the impersonated user.  Also, for the example below you will also need to include the following two namespaces that are new in TFS 2010:

using Microsoft.TeamFoundation.Framework.Client;
using Microsoft.TeamFoundation.Framework.Common;

Let’s see how our example looks using TFS Impersonation:

private void QueueBuildForUserUsingTFSImpersonation(
    TfsTeamProjectCollection currentUserCollection,
    String teamProjectName,
    String buildDefinitionName,
    String username)
{
    // Get the TFS Identity Management Service
    IIdentityManagementService identityManagementService =
            currentUserCollection.GetService<IIdentityManagementService>();

    // Look up the user that we want to impersonate
    TeamFoundationIdentity identity = identityManagementService.ReadIdentity(
            IdentitySearchFactor.AccountName, username, MembershipQuery.None, ReadIdentityOptions.None);

    TfsTeamProjectCollection impersonatedCollection = 
            new TfsTeamProjectCollection(currentUserCollection.Uri, identity.Descriptor);
    IBuildServer impersonatedBuildServer = impersonatedCollection.GetService<IBuildServer>();

    // Find the build definition for the build to queue.
    IBuildDefinition buildDefinition = GetBuildDefinition(impersonatedBuildServer, teamProjectName,
            buildDefinitionName);

    if (buildDefinition == null)
    {
        WriteToLog("Couldn't find build definition");
        return;
    }
    else
    {
        WriteToLog("Found build definition, queuing now...");
    }

    // Queue the build as our impersonated user.
    impersonatedBuildServer.QueueBuild(buildDefinition.CreateBuildRequest());

    WriteToLog("Build successfully queued");
}

As you can see in the example, the need for the user’s password is now gone. 

The only thing new to this example is how we discovered the user’s IdentityDescriptor by calling into the Identity Management Service.  This means that in order to use TFS Impersonation either the user’s account name or IdentityDescriptor is needed.  Some of the objects that are new to TFS 2010 will have the TeamFoundationIdentity or IdentityDescriptor objects available as properties so this extra call may not always be needed.  If not, the account name should be discoverable and the IdentityDescriptor can be resolved as it was above.

Wait, doesn’t it seem dangerous that one user can perform actions in Team Foundation Server on behalf of another user without that user’s password?

Yes!  Luckily, not everyone is able to do this.  Since TFS Impersonation actually takes place in the server (see the next section for more of an explanation on this) there is a permission in the server that controls who is and who is not allowed to perform impersonation.  This permission is titled “Make requests on behalf of others” and it can be managed for a Team Project Collection in the TPC security dialog within Team Explorer and it can be managed for the Configuration Server from within the Administer Security dialog off of the Application Tier node in the TfsMgmt console.

This permission is encapsulated within each Team Project Collection and within the Configuration Server.  This means that if User A has this permission on TPC1 he will not be allowed to impersonate users when talking to TPC2 or the Configuration Server.  Similarly, if User B has this permission on the Configuration Server she will not be able impersonate users when talking to any of the Team Project Collections.

Administrators should be very careful when granting this permission.  For the most part, it should only be granted to well-protected service accounts or tool accounts that can be trusted to take actions on behalf of other users.  Because of this, it is one of the few TFS permissions that is not automatically granted to the Configuration Server level or Team Project Collection level Administrators groups. 

Note, the following issue has been fixed in TFS 2010 RTM.  I will leave the description up for now since the betas are still heavily being used.

Unfortunately, the concept of not granting a permission to the Administrators group does not mesh well with the current TFS security dialog.  This is because that dialog makes the assumption that the Administrators group already has all of the permissions that it needs and actually does not allow you to change these permissions. 

In the above screenshot, the dialog is lying to you.  By default, the Administrators group does not have the “Make requests on behalf of others” permission.  Making things worse is that since the dialog prevents any permissions from being changed for the Administrators group the user is unable to actually give the Administrators group this permission using the UI. 

However, the ability to not set this permission may have a good consequence.  As discussed above, administrators should be very careful when granting this permission.  If it were given to the administrators group then this would mean that any administrator would be able to make a request on behalf of another user.  Now, granted, since they are an administrator they still have the power to grant this permission to them self but at least that takes an explicit action.

If it is decided that this permission needs to be given to the Administrators group then this is possible via the following command from the command-line:

tfssecurity.exe /collection:http://taylaf-dev:8080/tfs/Collection0 /a+ Server FrameworkGlobalSecurity Impersonate adm: ALLOW

Cool, is there anything else I should know about TFS Impersonation?

Of course!  We should definitely talk about the difference between an authenticated identity and the authorized identity and how they relate to TFS Impersonation.  In any web service call, the authenticated identity is the identity that authenticates with the web server (IIS in this case) and the authorized identity is the identity that the web application applies its internal permission restrictions to and is who it records as “performing” the given action.

In the normal case where impersonation is not being used, the authenticated identity and the authorized identity will always be the same.  For the first two examples in this post (Windows Impersonation and Using Different TFS Credentials) the authenticated and authorized identities for the web service calls will also be the same.  This is because in both of those cases, the web service call is being made by the user being “impersonated”.  Since this is true, both the authenticated and authorized identities refer to this “impersonated” user. 

As you might have guessed, these two identities will be different when TFS Impersonation is used.  When using TFS Impersonation the web service call is still made by the user running the process.  This means that the authenticated identity is the user running the process.  It isn’t until the web request enters the TFS web application and the “Make requests on behalf of others” permission is verified that the request becomes associated with the user being impersonated.  Thus, in this case the authorized identity is the identity that is being impersonated.

These ideas are exposed on the TfsConnection base class using the following properties:

public TeamFoundationIdentity AuthorizedIdentity { get; }

public void GetAuthenticatedIdentity(out TeamFoundationIdentity identity);

When there is an active ITeamFoundationImpersonationContext the AuthorizedIdentity property refers to the user being impersonated and the identity returned by GetAuthenticatedIdentity is the user doing the impersonation.

You may be wondering why we chose to implement the authenticated identity accessor as a method with an out parameter instead of a property like we did with AuthorizedIdentity.  The answer is that when a consumer of this API wants to know “who the active user is” in order to display some details about that user they should almost always show information for the user the who the requests are being made on behalf of (the authorized identity).  Because of this and because of how easy it is to confuse the authorized and authenticated identities we actually wanted to make it hard to get the authenticated identity.  Hopefully, this will prevent programmers from accidentally using the authenticated identity when they should be using the authorized identity and will force them to think about their scenario if they do think they should be using the authenticated identity.

Updated! Want to see another example using TFS Impersonation? Check out this example.

Hopefully that should be enough to get you started with TFS Impersonation.  I am sure there will be more posts about it as people ask more questions about it.  Speaking of, if you have questions feel free to ask in the comments or via the contact form.

If you are using TFS 2010 Beta 1 or Beta 2 then everything you just read is still true but some of the APIs have different names.  Here are the mappings that you will need to make this work in one of the betas:

TfsTeamProjectCollection is equivalent to TeamFoundationServer.  For more information on this see Grant Holliday's blog post.

In the Beta 2 version of this API you will not find the new constructors that are needed to perform the impersonation.  Instead, you will find a method off of the TeamFoundationServer object called ApplyThreadImpersonationContext().  This should be called immediately after constructing the TfsTeamProjectCollection object in order to do impersonation.

Before coming to North Carolina to work for Microsoft I spent the previous 18 years in Michigan.  I grew up in Cheboygan (yes, I am holding my hand up right now pointing to where Cheboygan is) and then went to college at the University of Michigan in Ann Arbor.  I will bleed Maize and Blue forever and yes, it is absolutely crushing me that our football team is missing a bowl game for the second year in a row.

Anyway, welcome to the blog and I hope you find something useful or entertaining to read.