This project has moved. For the latest updates, please go here.

Configuration

Distribution Media

The service can be shipped as a file system package. Which has been built and ZIP’d into a single file for ease of distribution in the downloads area (the solution also allows the building of a MSDeploy package)

The service can be built as a MSDeploy package. This can be installed in a variety of ways i.e. IIS Manager or command line, and into a dedicated web site or virtual application. The choice is yours at installation time.

This documentation assumes installation into a dedicated web site on your TFS server using the IIS Manager UI. You can however place the DSL endpoint on any IIS server your TFS server can see. 

Note that if placing the DSL endpoint on the same server as the TFS AT you need to consider Windows Loopback protection

Note that you can setup this service to make use of SSL or an existing site, this will require some additional setup steps, details of these can be found on Microsoft IIS documentation sites.

  1. On the TFS Server login as an admin user and load IIS Manager
  2. Expand the site section on the left
  3. Right click to add a new site
  4. Enter a name for the site e.g.TfsAlertService, notice that a new AppPool is created with the same name. (You can change the AppPool to make use of an existing AppPool if you want)
  5. Provide a physical path as the root folder for the web site e.g. c:\inetpub\TfsAlertService
  6. Select the port you wish to use for the site e.g. 8888
  7. You can confirm the values entered using the sites advanced settings and site bindings
    REMEMBER TO MAKE SURE THE FIREWALL DOES NOT BLOCK THE PORT YOU CHOOSE
  8. Save this new site settings
  9. In the AppPool settings find the newly create AppPool and edit its advanced settings to make sure that:
    • It is running .NET 4.0 Integrated (default is usually .NET 2.0)
    • In the advanced settings
      • Enable 32bit application is set to - True
      • The Identity is a user account that has rights to access TFS. You can do this by granting TFS rights to a build in account such as NetworkService, but it is probably better to a use a domain account. The TFSService account is a good choice as this already has all the rights it needs
  10. Once this is saved you should now have a new site to install your application into using MSDeploy, this can be done using the UI or command line
  11. Via the UI
    • In IIS Manager select the newly created site.
    • On the right hand side of the application select the Deploy, import application
    • Select the provide MSDeploy ZIP based package file (not the ZIP distribution emailed out, but the inner zip it contains)
    • Select the default options
    • Clear the application path field, and acknowledge the warning that ‘most applications are installed on folder’. You can of course install the application into a folder, the only effect is it will alter the service URL.
    • The application will then be installed
  12. Via the command line (alternative)
    • To perform a command line installation see the reference section of this document for link, but basically run the “TFSAlertrocessor.deploy.cmd’ PowerShell command to trigger MSDeploy with the parameters stored in the supporting files. The associated readme file provides more details.
  13. If not using MSDeploy

    • Unzip the file system distribution and place the files in the root of the new new site.

DSL Library

The main distribution media DOES NOT ship with an actual DSL library. This is because there is a good chance you will want to create your own.  So you therefore have three options

  • Create your own using samples provided
  • Download this projects source and build the provided reference implementation
  • THE EASIST OPTION - Download the TFSEventsProcessor.Dsl.dll implementation from the same page as the main release

Whichever option (or options, remember you can have multiple DSL libraries loaded at the same time) you choose place the DLL(s) in the folder specified in the web.config (see below)

Web.Config (usually done once)

All the service configuration is done via the IIS server web.config installed by MSDeploy into in the web site physical folder created in the previous steps. This can be edited manually as needed using Notepad or any other text editor.

You should not need to edit any of the WCF settings unless changing to SSL based communications.

<appSettings>
<!-- The domain name to append to the user names associated with work items –>
<add key="EmailDomain" value="mydomain.com"/>
<!-- If true logging will occur to the System.Diagnostics.Trace and incoming events are saved to the LoggingFolder –>
<add key="LogEventsToFile" value="True"/>
<!-- The folder that the service will use for a TFS Cache (needs read/write access)—>
<add key="WorkItemTrackingCacheRoot" value="C:\windows\temp"/>
<!-- The folder the incomming alerts will be dumped to if requested –>
<add key="LoggingFolder" value="C:\windows\temp"/>
<!-- Address of SMTP server used to send email –>
<add key="SMTPServer" value="mail.mydomain.com"/>
<!-- The email address that email should be sent from –>
<add key="FromEmail" value="tfsalert@mydomain.com"/>
<!-- The script to run when event raised either fill path or script name. V 1.1.x.x and later, if left blank it will try to use a script in the form '[eventname].py'—>
<add key="ScriptFile" value=" script.py"/>
<!-- The location to load DSL library from if no full path is used for the scriptfile entry—>
<add key="DSLFolder" value="C:\inetpub\TfsDslService\bin\DSL"/>
<!-- The location to load DSL library from-->
<add key="ScriptFolder" value="C:\inetpub\TfsDslService\Scripts"/>
</appSettings>

 

Registering Alerts

Using the Command Line

The easiest way to use the service is to configure TFS to send the alert message whenever something changes irrespective of the user. In this example the service will be called when any work item is changed

For this form of setup the command line tools on the TFS server can be used

"C:\Program Files\Microsoft Team Foundation Server 2012\Tools\bissubscribe" /eventType WorkItemChangedEvent /address http://localhost:8888/TfsAlertService.svc /collection http://localhost:8080/tfs/DefaultCollection

Note:

  • We can use the server name localhost as both TFS and the service are on the same box in this example.
  • If you have multiple team project collection you need to register each one separately

When the alert is registered you will be told a unique ID. The alert can be unsubscribed from the command line using the command

"C:\Program Files\Microsoft Team Foundation Server 2012\Tools\bissubscribe" /unsubscribe /id [the number]

Using the TFS Web Site

In many cases it will be easier to configure the alerts via the Alert Explorer in the TFS Web site. To do this:

  1. Open http://mytfsserver:8080/tfs
  2. Select a Team Project
  3. Select the the settings (cog top right)
  4. Select the Alerts tab
    Press the New Alert Button
  5. Select one of the alert templates (for the Work item alerts), this selects the basic filters. If you don’t want a filter (in effect the same as the command line subscription) pick blank alert
  6. Provide the alert a name
  7. On the alert definition tab set the
    1. Formatting: to SOAP
    2. Send to: to the WCF end point URL e.g. http://localhost:8888/TfsDslService.svc
  8. Save the alerts

Once the alert is registered, perform whatever action the alert traps and you should see the script being run.

If the script is not run use the techniques detailed in the debug section.

TOP TIPS

  • Make sure the URL you used in the alert registration matches the one for the actual IIS web site, typo's are easy to make.
  • If you are hosting the DSL endpoint on the same server as the TFS AT make sure Windows Loopback protection is disabled else you could get a TF30063 error - For details see this post

Last edited Feb 25, 2016 at 9:18 PM by rfennell, version 9