Connect to Team Foundation Server from a Console Application

You can programmatically connect to a server that is running Team Foundation and then access the team projects on that server if you use the following example. If you modify the example, you can use the services that Getting Additional Team Foundation Services describes later in this topic. You can also act on behalf of others by using impersonation, as Acting on Behalf of Another User (Impersonation) describes later in this topic.

In this topic

• Example

• Getting Additional Team Foundation Services

• Acting on Behalf of Another User (Impersonation)

  • Using a Team Foundation Identity

  • Using Authenticated Credentials

  • Using a Combination of Techniques

Example

You can list the team project collections and the team projects that they contain if you use the following example.

To use this example

1. Create a C# console application.

2. Add references to the following assemblies:

   • Microsoft.TeamFoundation.Common

   • Microsoft.TeamFoundation.Client

3. Replace the contents of Program.cs with the code that appears later in this topic.

4. In that code, replace Server, Port, and VDir in the URL that is used to construct the TfsConfigurationServer object so that the URL refers to your server.

   Tip

   To make sure that you are using the correct URL, use Team Explorer to open a team project on your server, and verify the URL properties of the server.

   

   using System;
   using System.Collections.ObjectModel;
   using Microsoft.TeamFoundation.Client; 
   using Microsoft.TeamFoundation.Framework.Common;
   using Microsoft.TeamFoundation.Framework.Client;
   
   namespace TfsApplication
   {
       class Program
       {
           static void Main(String[] args)
           {
               // Connect to Team Foundation Server
               //     Server is the name of the server that is running the application tier for Team Foundation.
               //     Port is the port that Team Foundation uses. The default port is 8080.
               //     VDir is the virtual path to the Team Foundation application. The default path is tfs.
               Uri tfsUri = (args.Length < 1) ? 
                   new Uri("http://Server:Port/VDir") : new Uri(args[0]);
   
               TfsConfigurationServer configurationServer =
                   TfsConfigurationServerFactory.GetConfigurationServer(tfsUri);
   
               // Get the catalog of team project collections
               ReadOnlyCollection<CatalogNode> collectionNodes = configurationServer.CatalogNode.QueryChildren(
                   new[] { CatalogResourceTypes.ProjectCollection },
                   false, CatalogQueryOptions.None);
   
               // List the team project collections
               foreach (CatalogNode collectionNode in collectionNodes)
               {
                   // Use the InstanceId property to get the team project collection
                   Guid collectionId = new Guid(collectionNode.Resource.Properties["InstanceId"]);
                   TfsTeamProjectCollection teamProjectCollection = configurationServer.GetTeamProjectCollection(collectionId);
   
                   // Print the name of the team project collection
                   Console.WriteLine("Collection: " + teamProjectCollection.Name);
   
                   // Get a catalog of team projects for the collection
                   ReadOnlyCollection<CatalogNode> projectNodes = collectionNode.QueryChildren(
                       new[] { CatalogResourceTypes.TeamProject },
                       false, CatalogQueryOptions.None);
   
                   // List the team projects in the collection
                   foreach (CatalogNode projectNode in projectNodes)
                   {
                       Console.WriteLine(" Team Project: " + projectNode.Resource.DisplayName);
                   }
               }
           }
       }
   }
   

   Imports System
   Imports System.Collections.ObjectModel
   Imports Microsoft.TeamFoundation.Client
   Imports Microsoft.TeamFoundation.Framework.Common
   Imports Microsoft.TeamFoundation.Framework.Client
   
   Module Module1
   
       Sub Main(ByVal sArgs() As String)
   
           ' Connect to the Team Foundation Server
           ' Server is the name of the server running the application tier for Team Foundation Server
           ' Port is the port that the Team Foundation Server uses. The default port is 8080.
           ' VDir is the virtual path to the Team Foundation application. The default value is tfs.
           Dim tfsUri As Uri
           If sArgs.Length = 0 Then
               tfsUri = New Uri("https://Server:8080/tfs")
           Else
               tfsUri = New Uri(sArgs(1))
           End If
   
           Dim configurationServer As New TfsConfigurationServer(tfsUri)
           configurationServer = TfsConfigurationServerFactory.GetConfigurationServer(tfsUri)
   
           ' Get the catalog of team project collections
           Dim collectionNodes As ReadOnlyCollection(Of CatalogNode)
           Dim gVar As Guid() = New Guid() {CatalogResourceTypes.ProjectCollection}
           collectionNodes = configurationServer.CatalogNode.QueryChildren(gVar, False, CatalogQueryOptions.None)
   
           ' List the team project collections
           For Each collectionNode In collectionNodes
               Dim collectionId As Guid = New Guid(collectionNode.Resource.Properties("InstanceID"))
   
               Dim teamProjectCollection As New TfsTeamProjectCollection(tfsUri)
               teamProjectCollection = configurationServer.GetTeamProjectCollection(collectionId)
               System.Console.WriteLine("Collection:" + teamProjectCollection.Name)
   
               ' Get a catalog of team projects for the collection
               Dim hVar As Guid() = New Guid() {CatalogResourceTypes.TeamProject}
   
               Dim projectNodes As ReadOnlyCollection(Of CatalogNode)
               projectNodes = collectionNode.QueryChildren(hVar, False, CatalogQueryOptions.None)
   
               ' List the team projects in the collection
               For Each projectNode In projectNodes
                   System.Console.WriteLine(" Team Project: " + projectNode.Resource.DisplayName)
               Next
   
           Next
   
   
       End Sub
   
   End Module
   

Getting Additional Team Foundation Services

You can access additional services by using one of the GetService methods that the abstract class TfsConnection defines and that TfsConfigurationServer and TfsTeamProjectCollection implement.

• GetService<T>()

• GetService(Type)

• GetServiceInstance(Type, Object)

When you use the TfsConfigurationServer class, you access the services for the whole server. When you use the TfsTeamProjectCollection class, you access the services for the team project collection. For example, the ITeamFoundationRegistry service for TfsConfigurationServer provides registered properties of the server. The same service that is acquired from TfsTeamProjectCollection provides the registered properties of a team project collection. Some services apply to team project collections only.

Service	TfsConfigurationServer (server-level)	TfsTeamProjectCollection (collection-level)
ITeamFoundationRegistry
IIdentityManagementService
ITeamFoundationJobService
IPropertyService
IEventService
ISecurityService
ILocationService
TswaClientHyperlinkService
ITeamProjectCollectionService
IAdministrationService
ICatalogService
VersionControlServer
WorkItemStore
IBuildServer
ITestManagementService
ILinking
ICommonStructureService3
IServerStatusService
IProcessTemplates

Acting on Behalf of Another User (Impersonation)

When you connect to Team Foundation Server, you can use a method that supports impersonation to act on behalf of an identity other than the one that runs your application. Any operations that are performed based on that connection will be performed on behalf of the impersonated identity. For example, your application could run under the identity of User A but create a connection to Team Foundation Server that impersonates User B. If User A checks in a change to source code under these conditions, the changeset will record that User B checked in the change.

Using a Team Foundation Identity

You can use an IdentityDescriptor object when you connect to Team Foundation Server to specify the identity to impersonate. The IdentityDescriptor specifies an identity that Team Foundation defines. When you use this strategy, you do not need to specify a password. The authenticated identity must have the Make requests on behalf of another user permission, except when the authenticated (User A) and impersonated (User B) identities are the same.

Server-level
TfsConfigurationServer.TfsConfigurationServer(RegisteredConfigurationServer, IdentityDescriptor) TfsConfigurationServer.TfsConfigurationServer(Uri, IdentityDescriptor)

Collection-level
TfsTeamProjectCollection.TfsTeamProjectCollection(RegisteredProjectCollection, IdentityDescriptor) TfsTeamProjectCollection.TfsTeamProjectCollection(Uri, IdentityDescriptor)

Using Authenticated Credentials

You can use an ICredentials object when you connect to Team Foundation Server to specify the identity to impersonate. This strategy does not require special permissions, but you must be able to obtain the password of the identity to create the ICredentials object.

You can also specify an implementation of ICredentialsProvider when you connect to Team Foundation Server to handle requests for new credentials. The system calls the implementation of ICredentialsProvider that you specify to request new credentials when the credentials that are specified by the ICredentials object are not successfully authenticated or authorized to perform the operation.

To prompt the user for credentials, you can use the UICredentialsProvider class, which implements ICredentialsProvider by displaying a logon dialog box to prompt the user for new credentials.

Server-level

TfsConfigurationServer.TfsConfigurationServer(RegisteredConfigurationServer, ICredentials, ICredentialsProvider) TfsConfigurationServer.TfsConfigurationServer(Uri, ICredentials, ICredentialsProvider) TfsConfigurationServerFactory.GetConfigurationServer(Uri, ICredentialsProvider) TfsConfigurationServerFactory.GetConfigurationServer(RegisteredConfigurationServer, ICredentialsProvider) TfsConfigurationServer.TfsConfigurationServer(Uri, ICredentialsProvider)

Collection-level

TfsTeamProjectCollection(RegisteredProjectCollection, ICredentials, ICredentialsProvider) TfsTeamProjectCollection.TfsTeamProjectCollection(Uri, ICredentials, ICredentialsProvider) TfsTeamProjectCollectionFactory.GetTeamProjectCollection(Uri, ICredentialsProvider) TfsTeamProjectCollectionFactory.GetTeamProjectCollection(RegisteredProjectCollection, ICredentialsProvider) TfsTeamProjectCollection.TfsTeamProjectCollection(Uri, ICredentialsProvider)

Using a Combination of Techniques

You can use both a Team Foundation identity and authenticated credentials when you connect to Team Foundation Server. For example, your application might run under credentials for User A, but you might use credentials for User B and specify an IdentityDescriptor for User C when you connect to Team Foundation Server. In this case, requests that are made by using that connection are authenticated as User B but performed on behalf of User C. For this strategy to succeed, User B must have the Make requests on behalf of another user permission.

Server-level
TfsConfigurationServer.TfsConfigurationServer(RegisteredConfigurationServer, ICredentials, ICredentialsProvider, IdentityDescriptor) TfsConfigurationServer.TfsConfigurationServer(Uri, ICredentials, ICredentialsProvider, IdentityDescriptor)

Collection-level
TfsTeamProjectCollection.TfsTeamProjectCollection(RegisteredProjectCollection, ICredentials, ICredentialsProvider, IdentityDescriptor) TfsTeamProjectCollection.TfsTeamProjectCollection(Uri, ICredentials, ICredentialsProvider, IdentityDescriptor)

Additional Resources

Organize your server with team project collections

Connect to team projects in Team Foundation Server

Introducing the TfsConnection, TfsConfigurationServer, and TfsTeamProjectCollection Classes on the Microsoft website

Using TFS Impersonation with Version Control APIs on the Microsoft website.