Visual Studio Integrate – REST API und Service Hooks

VSOIntegrateIn Houston findet derzeit die TechEd North America  2014 statt, auf der Microsoft wieder zahlreiche Neuigkeiten für IT Professionals und Software-Entwickler veröffentlicht hat. Eine langersehnte Erweiterung für den Team Foundation Server wurde ebenfalls bekannt gegeben: die neuen REST APIs und Service Hooks. Microsoft hat dafür ein neues Portal veröffentlicht – Visual Studio Integrate.

Brian Harry schreibt in seinem Blog, dass Microsoft die Integrationsfähigkeit des TFS (vorerst nur Visual Studio Online) zu anderen Tools und Services, sowie die Anbindung an mobile Geräte stark vereinfachen wollte. Die neue REST-API, OAuth und die Service Hooks basieren deshalb auf standardisierter Web-Technologie, um einen möglichst breiten Zuspruch bei allen Anwendern zu erhalten. S. Somasegar erwartet eine Vielzahl von 3rd Party Apps und Services, die die neuen Integrationsmöglichkeiten nutzen werden. Grund genug, um die neue Integration Platform etwas genauer anzusehen.

Integration in Visual Studio

Mit der neuen API, OAuth und den Service Hooks öffnet Microsoft  allen Nutzern, Entwicklern und ALM Partnern den Cloud Service und lädt dazu ein, zahlreiche Erweiterungen für Visual Studio Online zu entwickeln. Damit folgt auch die ALM Plattform dem neuen Trend von Microsoft, seine Technologien und Plattformen der Entwickler-Community zur Erweiterung und Mitarbeit zur Verfügung zu stellen.

Die neuen Mechanismen und Funktionen in Visual Studio Online ermöglichen es vielen populären Cloud Diensten (wie Trello, GitHub, Jenkins) einen Zugang zur ALM Plattform zu bekommen. Ebenso wird die Integration von externen Anwendungen und Diensten, sowie der Abruf von Daten zur Aufbereitung in 3rd Party Apps stark vereinfacht. Die ALM Plattform wird dadurch noch „persönlicher“, da sie durch die möglichen Erweiterungen besser an die jeweiligen Bedürfnisse angepasst werden kann.

IntegrationPortalAbbildung 1: Visual Studio Integrate Portal

Mögliche Szenarios nennt Microsoft im Visual Studio Integration Portal auch gleich selbst:

  • Daten in mobilen Apps aufbereiten
  • Externe Dienste anbinden, wie z.B. externe Build Systeme
  • Integrations-Mechanismen mit externen Systemen, wie z.B. externe Ticket-Systeme
  • Push-Notifikationen für mobile Anwendungen
  • Integration des Team Foundation Servers (on-prem)

REST API

Ein wichtiger Punkt gleich zu Beginn: nur Visual Studio Online wird die neue API  zur Verfügung stellen. Der Team Foundation Server wird dies erst in einer zukünftigen Version ermöglichen.

Die neue REST API ist unter anderem so interessant, weil man damit von praktisch jedem Gerät, Plattform oder Technology Stack, Daten von Visual Studio Online abrufen und Usern aufbereitet in einer Anwendung oder App zur Verfügung stellen kann. Und dafür genügt ein simpler http-Aufruf.

Über die API lassen sich Daten abrufen und manipulieren. Auch wenn die API erst in Version 1.0 preview ist, werden bereits folgende Bereiche unterstützt (wenn auch nur eingeschränkt):

  • Build Informationen
  • Version Control und Git
  • Team Room Nachrichten
  • Work item Tracking
  • Test Management
  • usw.

Die Folgenden Code Snippets zeigen ein paar einfache Aufrufe aus einer Windows 8.1 App und ermöglichen das Auslesen von Work Item Detailinformationen aus einem Team Projekt.

Dazu werden als Erstes alle Queries aus dem Team Projekt ALMSports ausgelesen. Anschließend wird mit der ID einer bestimmten Query ein Post-Request abgesetzt, um alle Work Item IDs der Query ausfindig zu machen.

Alle Work Item Queries aus Team Projekt abfragen

using (var httpClient = new HttpClient())
{
    var responseStream = await httpClient.GetAsync(
       new Uri(<a href="https://kkempe.visualstudio.com/defaultcollection/_apis/wit/queries?project=almsports">https://kkempe.visualstudio.com/defaultcollection/_apis/wit/queries?project=almsports</a>));
    string strResponse = await response.Content.ReadAsStringAsync();
 
   // Parse json response
}

Abfrage mit bestimmter Query-Id absetzen

using (var httpClient = new HttpClient())
{
    // use id of the query
    JObject query = JObject.FromObject(new { id = "60522067-a094-4c75-83f1-ef07a8dbcd0b" }); 
    httpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));
    var response = await httpClient.PostAsync(
       new Uri("https://kkempe.visualstudio.com/defaultcollection/_apis/wit/queryresults),
       new StringContent(query.ToString(), Encoding.UTF8, "application/json")
    );
    string strResponse = await response.Content.ReadAsStringAsync();
 
    // Parse json response 
}

Detailinformation für Work Item mit ID=10 abfragen

using (var httpClient = new HttpClient())
{
    var responseStream = await httpClient.GetAsync(
       new Uri("https://kkempe.visualstudio.com/defaultcollection/_apis/wit/ workitems?ids=10")
    );
    string strResponse = await response.Content.ReadAsStringAsync();
 
   // Parse json response
}

Service Hooks

Mit Hilfe der Service Hooks für Visual Studio Online können sich Apps oder Services benachrichtigen lassen, wenn ein bestimmtes Event in VSO ausgelöst wird. Somit bekommen Sie Änderungen bei Builds, Check-Ins oder Work Items mit, ohne dass ein ständiges Pollen nach Neuigkeiten notwendig ist. Bereits zur Veröffentlichung des Integration Portals sind einige Dienste bereitgestellt worden, für die sich eine Anwendung oder ein Dienst ein Abonnement erstellen kann.

service hooksAbbildung 2: Subscription Wizard für Service Hooks

Um ein Abonnement zu erstellen, wird im Administrationsbereich eines Team Projekts in Visual Studio Online eine neue Lasche „Service Hooks“ angeboten (per Default haben nur Projekt Admins die Berechtigung eine Subscription zu erstellen). Um eine Subscription zu erzeugen, muss der Anwender ein dickes grünes Kreuz anklicken und wird anschließend mit Hilfe eines Wizards durch den Abonnement-Prozess geführt. Eine genaue Beschreibung findet Ihr hier.

OAuth

OAuth 2.0 heißt das Zauberwort in Visual Studio Online. Dieser Authentifizierungsmechanismus soll dafür sorgen, dass Anwender nicht ständig nach Username und Passwort gefragt werden, wenn Sie eine Abfrage beispielsweise aus einer App heraus tätigen. Dafür muss die App im Vorfeld registriert und anschließend vom Benutzer für die Verwendung von VSO autorisiert werden. Der genaue Mechanismus kann auf der Get Started Seite im Visual Studio Integrate Portal nachgelesen werden.

OAuthAbbildung 3: Authentifizierungsmechanismus von OAuth2.0 für die REST Api

Dokumentation

http://www.visualstudio.com/en-us/integrate/explore/explore-vso-vsi

Links

http://integrate.visualstudio.com
http://blogs.msdn.com/b/bharry/archive/2014/05/12/a-new-api-for-visual-studio-online.aspx
http://blogs.msdn.com/b/somasegar/archive/2014/05/12/visual-studio-online-rest-apis-and-service-hooks.aspx