Was sind Service Hooks?

Service Hooks dienen dazu, auf Ereignisse reagieren zu können, die in einem Team Projekt auftreten. Zu den Ereignissen zählen beispielsweise die Veränderung eines Work Items oder die Fertigstellung eines Builds. Neben der Übermittlung einfacher Nachrichten für Teamchats ist es auf diese Weise beispielsweise auch möglich, Daten von Work Items in andere Systeme zu integrieren oder deren Daten zusammenzufassen.

Eine Auflistung der unterstützten Ereignisse ist in der Dokumentation zu finden. Service Hooks werden in Visual Studio Team Services oder einer on-premise Installation des Microsoft Team Foundation Servers ab Version 2015 unterstützt. Während on-premise früher Team Foundation Server Plugins genutzt werden konnten, um eine ähnliche Funktionalität zu erreichen, sind die Service Hooks eine Cloud-verträgliche Möglichkeit, die ohne Zugriff auf das Installationsverzeichnis des Servers verwendet werden können.

Die Registrierung von Abonnenten (“Subscriber”) für Service Hooks erfolgt in der Administration des Team Projekts:

Beim Anlegen einer neuen Registrierung wird zunächst der Dienst, mit dem die Integration erfolgen soll, ausgewählt. Hierbei gibt es bereits einige Dienste wie beispielsweise Azure Service Bus oder Slack, die out-of-the-box angeboten werden und einfach konfiguriert werden können:

Auf den folgenden Seiten wird der Dienst konfiguriert. Dazu zählen die Verbindungseinstellungen, die natürlich je nach Dienst unterschiedlich sind. Darüber hinaus wird das Ereignis ausgewählt, für das die Registrierung gilt. Die unterstützten Ereignisse unterscheiden sich von Dienst zu Dienst. Auch das Filtern der Ereignisse ist möglich, um bereits frühzeitig unnötigen Traffic zu vermeiden.

Eigene WebHook Receiver entwickeln

Zur Abbildung eigener Abonnement-Szenarien, gibt es mit der Option WebHook eine Möglichkeit, beim Auftreten eines Ereignisses einen Post an eine Web-Anwendung zu senden. Hierfür gibt es mit den ASP.NET WebHooks und den Receivern bereits eine gute Unterstützung, so dass die Umsetzung schnell erfolgen kann. Für VSTS und TFS gibt es einen speziellen Receiver, der im Nuget-Paket Microsoft.AspNet.WebHooks.Receivers.VSTS vorhanden ist. Ein Codebeispiel ist auf Github abgelegt.

Um einen WebHook Receiver in einem ASP.NET-Projekt zu implementieren, muss in diesem die Web API aktiviert sein. Anschließend kann das Nuget-Paket installiert werden.

Zur Aktivierung muss folgende Zeile in der Datei WebApiConfig.cs hinzugefügt werden:

config.InitializeReceiveVstsWebHooks();

Die Zugriffe auf WebHooks werden auf zweierlei Art abgesichert; einerseits muss bei jedem Request ein Code übergeben werden, der nur dem Receiver und dem Service bekannt ist. Im Fall des VSTS Receivers muss dieser zwischen 32 und 128 Zeichen lang sein; ein guter Code kann beispielsweise als HMAC online generiert werden. Dieser Code wird als AppSetting in der web.config abgelegt (in Azure kann dies natürlich auch auf Ebene der Web-Anwendung erfolgen):

<add key="MS_WebHookReceiverSecret_VSTS" value="***"/>

Außerdem wird bei nicht-lokalen Aufrufen erwartet, dass der Aufruf per SSL erfolgt. Insbesondere beim Entwickeln für einen on-premise TFS sollten Tests deshalb auf dem TFS-Server ausgeführt werden, weil auch die Verwendung eines Self-Signed-Zertifikates im IIS Express beim Aufruf des WebHooks zu einem Fehler führt. Über die Einstellung MS_WebHookDisableHttpsCheck kann dieses Verhalten in der web.config jedoch angepasst werden.

Nach der Konfiguration des Sicherheitscodes kann mit der Umsetzung des eigentlichen Handlers begonnen werden. Diese ist insofern sehr einfach, dass für ASP.NET WebHook Handler lediglich eine Klasse erzeugt werden muss, die die Schnittstelle IWebHookHandler implementiert. Zur Laufzeit werden diese dann automatisch geladen, ohne dass eine Konfiguration notwendig ist. Für VSTS WebHook Handler gibt es folgende Basisklasse:

Microsoft.AspNet.WebHooks.VstsWebHookHandlerBase

Diese prüft bereits, welches Ereignis übermittelt wird und stellt die entsprechenden Daten als .NET-Objekte bereit. So kann beispielsweise direkt die Methode ExecuteAsync(WebHookHandlerContext context, WorkItemUpdatedPayload payload) überschrieben werden, wenn man an den Änderungen eines Work Items interessiert ist:

public class DemoVstsWebhookHandler : VstsWebHookHandlerBase
{
    public override Task ExecuteAsync(WebHookHandlerContext context, WorkItemUpdatedPayload payload)
    {
        // Handle workitem.updated event
    }
}

Nach der Implementierung des Receivers muss das Abonnement der Ereignisse noch im TFS angelegt werden. Als Typ wird wenig überraschend WebHook ausgewählt. Nach der Einstellung des Events und der Filter werden die Verbindungsinformationen zum WebHook auf der zweiten Seite angegeben:

Die URL wird folgendermaßen angegeben:

http://localhost:1234/api/webhooks/incoming/vsts/{id}?code={code}.

http://localhost:1234 wird durch das entsprechende Protokoll, Servernamen und Port ersetzt. Durch Angabe der {id} kann ein String angegeben werden, der den Versender identifiziert. Dieser Teil kann jedoch auch entfallen. Als {code} wird der Sicherheitscode verwendet.

In den Feldern Ressource details to send, Messages to send und Detailed messages to send kann eingestellt werden, welche Informationen in welcher Tiefe an den WebHook übermittelt werden sollen. Insbesondere bei fremden WebHooks sollten diese natürlich möglichst knapp sein.

Der Test-Button erlaubt das einfache Prüfen der Einstellungen, so dass besonders beim Debuggen nicht jedes Mal das wirkliche Ereignis provoziert werden muss.

Nach dem Klick auf Finish ist das Abonnement eingerichtet. Falls die Anlage des Abonnements häufiger erfolgen soll, kann auch dies durch eine Extension vereinfacht werden.