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

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:

    Note

    If Microsoft.TeamFoundation.Client and Microsoft.TeamFoundation.Common do not appear on the .NET tab of the References dialog box, use the Browse tab to add the assemblies. You can find them at %ProgramFiles%\Microsoft Visual Studio 10.0\Common7\IDE\ReferenceAssemblies\v2.0.

  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.

    Team Foundation Server Properties: URL

    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("http://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.

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

check mark

check mark

IIdentityManagementService

check mark

check mark

ITeamFoundationJobService

check mark

check mark

IPropertyService

check mark

check mark

IEventService

check mark

check mark

ISecurityService

check mark

check mark

ILocationService

check mark

check mark

TswaClientHyperlinkService

check mark

check mark

ITeamProjectCollectionService

check mark

IAdministrationService

check mark

check mark

ICatalogService

check mark

VersionControlServer

check mark

WorkItemStore

check mark

IBuildServer

check mark

ITestManagementService

check mark

ILinking

check mark

ICommonStructureService3

check mark

IServerStatusService

check mark

IProcessTemplates

check mark

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

Collection-level

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

Organizing Your Server with Team Project Collections

Connect to and Access 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.