API TFS – Se connecter et démarrer

L’API TFS permet de tout faire (ou presque) pour manipuler TFS, que ce soit au niveau du serveur lui-même ou des collections. Quel besoin a-t-on de manipuler  TFS via ses APIs alors que tout (ou presque) est disponible via une IHM ? L’automatisation pardi ! Je ne sais pas vous, mais reconfigurer une ferme de build d’une cinquantaine de machines, je ne fais pas ça à la main 🙂

Dans ce premier billet, nous allons voir comment nous connecter à un serveur TFS puis à une collection et enfin manipuler l’API pour agir sur TFS.

Petit rappel de fonctionnement

TFS 2010 a été un gros changement au niveau du fonctionnement. Jusqu’en 2008, il y avait le serveur TFS et… c’était tout ! TFS 2010 a introduit la notion de « collection » et est alors devenu une sorte d’ensemble de serveurs logiques (les collections) regroupés au sein d’un unique serveur (le serveur TFS).

Principes communs

Que ce soit pour se connecter au serveur ou à une collection, il y a une approche commune. Nous allons en utiliser deux types par la suite qui héritent d’ailleurs d’un même type de base : TfsConnection. Ils se différencient principalement par leur cible et les services qu’ils proposent.

Pour attaquer les APIs TFS, il faut d’abord référencer les bonnes assemblies depuis le GAC. Si vous avez plusieurs versions de Visual Studio installées, faites attention à référencer les mêmes versions de ces deux assemblies :

• Microsoft.TeamFoundation.Client
• Microsoft.TeamFoundation.Common

Importez, au moins, le namespace suivant : Microsoft.TeamFoundation.Client

La connexion à un serveur TFS n’a, en soi, rien de complexe :

var confServer = TfsConfigurationServerFactory.GetConfigurationServer(uri);

Où uri est l’adresse racine du serveur TFS. En général, c’est quelque chose qui ressemble à ça : http://monserveur:8080/tfs

Et à une collection :

var collection = TfsTeamProjectCollectionFactory.GetTeamProjectCollection(uri);

Où uri est l’adresse de la collection. En général, cela donne quelque chose qui ressemble à ça : http://monserveur:8080/tfs/macollection

Jusque-là, rien de bien sorcier. Dans les exemples de ce billet, je référence une instance TFS que j’ai enregistrée via le menu « Select Team Projects » de Visual Studio. De ce fait, mes informations d’authentification sont connues de l’API TFS. Il existe cependant des surcharges aux méthodes précédentes pour gérer toute la partie authentification. Je ne vais pas m’attarder dessus, celles-ci étant plutôt claires.

Je suis connecté et maintenant ?

Et bien maintenant, il est temps d’utiliser les services que nous propose l’API TFS pour commencer à en manipuler les éléments.

Pour des raisons de simplicité (après tout, ce billet n’est qu’une introduction), je manipulerai des services au niveau collection uniquement, ce sera plus parlant.

Je parle de services depuis le début, mais qu’est-ce que c’est ?

Une connexion TFS (serveur ou collection) ne propose pas grand-chose de base. Il faut passer par des services particuliers comme nous allons le faire avec les builds par exemple.

Chaque service correspond, en fait, à un domaine fonctionnel de TFS : les builds, la gestion des sources, les workitems ou encore la sécurité.

Dans l’exemple qui suit, nous allons lister les différents composants de build qui sont disponibles au niveau de notre collection.

Pour continuer, on rajoute simplement une référence à Microsoft.TeamFoundation.Build.Client.dll qui contient le service qui nous permettra de manipuler les builds et tout ce qui va autour dans TFS. Pour rester cohérent, il est nécessaire de prendre la même version d’API que pour la connection.

Et on importe le namespace Microsoft.TeamFoundation.Build.Client

Pour cela, il faut récupérer un service de type IBuildServer :

// On se connecte à la collection
var collection = TfsTeamProjectCollectionFactory.GetTeamProjectCollection(uri);

// On récupère le service de gestion de la partie build de TFS
var buildServer = collection.GetService<IBuildServer>();

// On créé une requête pour la recherche
var spec = buildServer.CreateBuildControllerSpec("*", "*");
spec.IncludeAgents = false;

// On exécute la recherche et on récupère nos contrôleurs
var controllers = buildServer.QueryBuildControllers(spec).Controllers;

Si tout se passe correctement, controllers doit ressembler à quelque chose comme ça :

Un petit mot sur les APIs TFS

Compatibilité

Ceux qui suivent l’actualité TFS savent que depuis TFS 2012, les updates sont plus fréquentes (les fameuses Update X ou encore TFS 201X.Y).

Dans l’ensemble, les différentes Updates n’apportent pas de changements majeurs sur le contrat des APIs existantes, contrairement aux versions majeures. Il peut, en revanche, y avoir des ajouts comme ce fut le cas avec le support de GIT.

Retro-compatibilité

Les APIs TFS, et c’est une très bonne chose, permettent de cibler des versions plus anciennes de TFS. Bien sûr, il y a quelques limitations à cela (fonctionnalités, gros changement TFS, …), mais il est tout à fait envisageable de cibler un TFS 2010 avec les APIs 2013. Des utilitaires écrits avec les APIs 2013 pourront donc vous servir sur de plus anciennes versions.

Plateforme cible

Un autre point à garder dans un coin de la tête : Si la plupart des assemblies contenant les APIs TFS sont compilées en MSIL, il y en a une, en particulier, qui peut poser problème puisqu’elle référence une DLL native compilée en 32bits : Microsoft.TeamFoundation.WorkItemTracking.Client.DataStoreLoader.

Elle est référencée par Microsoft.TeamFoundation.WorkItemTracking donc attention à la manipulation des Workitems dans des applications 64bits.

Et ensuite ?

Ce billet est une introduction. Il ne sert qu’à découvrir ou redécouvrir le fonctionnement de base de l’API TFS. On verra dans un prochain billet comment utiliser cette API pour générer une photo de notre infrastructure TFS.