Per Code mit TFS-WorkItems arbeiten

Installation TFS API Libraries

Um auf den TFS zugreifen zu können, ist das NuGet-Paket TeamFoundation.11 zu installieren.

PM> Install-Package TeamFoundation.11

Zugriff auf den TFS

Ist am Rechner ein Workspace bereits vorhanden, kann mit dem folgenden Code alles Notwendige für den Zugriff auf die WorkItems erstellt werden:

var collectionSource = new Uri("http://tfs-server:port/tfs/MyCollection");
var collection = TfsTeamProjectCollectionFactory.GetTeamProjectCollection(collectionSource);
var store = collection.GetService<WorkItemStore>();

Auch eine Authentifizierung mittels Username und Passwort ist möglich, hierzu sind die ClientCredentials der Collection zu setzen und die Authentfizierung manuell zu triggern:

NetworkCredential netCred = new NetworkCredential("UserName", "Password");
WindowsCredential winCred = new WindowsCredential(netCred);
TfsClientCredentials tfsCred = new TfsClientCredentials(winCred);

collection.ClientCredentials = tfsCred;
collection.Authenticate();

WorkItems vom TFS abfragen

Nun kann man sich mit der TFS WorkItem Query sämtliche WorkItems abfragen.

var query = "SELECT [System.Id], [System.Title] FROM WorkItems WHERE [System.ID] > 1000";
var items = store.Query(query);

In diesem Fall werden Id und Titel abgefragt und “als geöffnet” markiert. Änderungen an diesen Eigenschaften können somit vorgenommen werden.

Ein andere Möglichkeit besteht darin, sich alle Felder zurückgeben zu lassen.

var query = "SELECT * FROM WorkItems WHERE [System.ID] > 1000";
var items = store.Query(query);

Hier werden alle Informationen geladen, allerdings wird keine Eigenschaft “als geöffnet” markiert. Wird eine Eigenschaft aktualisiert und gespeichert, kommt es zu nachfolgender Ausnahme:

Microsoft.TeamFoundation.WorkItemTracking.Client.ValidationException: TF400276: You have tried to set a value for a field of a work item which is not opened or partial opened. You cannot set a value for a field of a work item which is not opened or partial opened.

Dies kann nun umgangen werden, indem zu aktualisierende Eigenschaften explizit in der Query angegeben werden, oder aber, indem das jeweilige Item mittels Aufruf der Methode Open geöffnet wird.

Auf benutzerdefinierte Eigenschaften zugreifen

Der TFS erlauft die Konfiguration von benutzerdefinierten Eigenschaften. Diese sind natürlich im Objektmodell nicht explizit bekannt. Das WorkItem bietet die Auflistung Fields an. Darüber können auch diese Felder abgerufen werden. Die Abbildung in der Datenbank sieht wie folgt aus:

Die benutzerdefinierten Felder werden fortlaufend nummeriert. Start ist 10000. Als Prefix wird für die DB “Fld” vergeben.

Um nun auf ein derartiges Feld zugreifen zu können, stellt die Auflistung Fields die Methode GetById zur Verfügung.

// item is WorkItem
var customFieldVal = item.Fields.GetById(10000).Value;

WorkItem speichern

Vorgenommene Änderungen können natürlich auch gespeichert werden. Dazu bietet das WorkItem die Methode Save an.

try {
  item.Save();
}
catch (ValidationException ex) {
  // handle exception
}

Beim Speichern werden Validierungsregeln angewandt und bei Nichterfüllung eine entsprechende Ausnahme geworfen.

Eine Prüfung im Vorfeld kann mittels IsValid und Validate (beides am WorkItem verfügbar) durchgeführt werden.

Sollen viele WorkItems aktualisiert werden, bietet sich eine Batch-Aktualisierung an, diese kann über den WorkItemStore durchgeführt werden:

var query = "SELECT * FROM WorkItems WHERE [System.ID] > 1000";
var items = store.Query(query);

...

store.BatchSave(items);

Finger weg von der Datenbank

Immer wieder findet man Beiträge, die Änderungen in der Datenbank vorschlagen. Davon ist Abstand zu nehmen, da die WorkItems über mehrere Tabellen hinweg gehalten werden (WorkItemsAre, WorkItemsLatest, WorkItemsWere). Direkte Änderungen können sich schnell fatal auswirken. Daher empfehle ich, immer über die API zu gehen.

Fazit

Dieser Beitrag hat zahlreiche Hilfsmittel für die Verwendung der TFS-API aufgezeigt. Damit sollten viele hilfreiche Szenarien einfach abzubilden sein. Ich denke hierbei an diverse Statistiken, Migrationen, Prozesse, die Informationen bei WorkItems hinterlegen usw. Tests sollten immer gegen ein entsprechendes Testsystem durchgeführt werden, aber das versteht sich von selbst.