Team Foundation Server Integration using QTfsListener

Transcription

1 VaraLogix Q Team Foundation Server Integration using QTfsListener Table of Contents Introducing QTfsListener QTfsListener executable command line options Register QTfsListener as a service Establishing service account to run QTfsListener Edit configuration settings Edit the Qmappings.xml file Configuring and starting the QTfsListener service Start the QTfsListener service Troubleshooting... 6

2 Introducing QTfsListener The QTfsListener is a service that integrates the Microsoft 2010 Team Foundation Server with the VaraLogix Q Deployment System. The QTfsListener subscribes to Team Foundation Build Quality Change events and interfaces with the Q API to create a Q package instance. Figure 1 shows the processing for the QTfsListener. The process consists of the following steps: 1. The QTfsListener subscribes to Team Foundation Build Quality Change events. 2. A user changes a Build Quality using the Microsoft TFS Team Explorer. 3. The Team Foundation Build Store tells the Team Foundation Event Service that a Build Quality has changed. 4. The Team Foundation Event Service queries the Team Foundation Event Subscription Store to see if anyone has subscribed for Build Quality Change Events. In this case, it pulls the QTfsListener subscription information. 5. The Team Foundation Event Service sends a Build Quality Change Event to the QTfsListener service. 6. QTfsListener opens the Qmappings.xml file and compares the Build Quality Change Event to the criteria for Q package instance creation. 7. QTfsListener uses the Q API to create a Q package instance (and optionally deploy the instance). 8. If configured in Qmappings.xml, the Build Quality of the build corresponding to the received Build Quality Event is changed based upon the success or failure of the Q package instance creation. Page 2 of 7

3 TFS Application/Database Server 2 User running TFS Exploer User changes Build Quality TFS Build Store TFS Event Subscription Store Subscriber Information 4 3 Build Quality Change Event TFS Event Service 8 Post Q processing Build Quality Change (optional) Subscribe to TFS Build Quality Change Events 1 5 Build Quality Change Event Q Instance Creation QTFSListener Q API Server 7 Map Event to Instance Data 6 Qmappings.xml Event Listener Machine Figure 1 QTfsListener Process Page 3 of 7

4 1. QTfsListener executable command line options The QTfsListener calling syntax is: QTfsListener.exe i u d The options are: -i - installs QTfsListener as a service -u - uninstalls the QTfsListener service -d - runs QTfsListener in the foreground in debug mode. 2. Register QTfsListener as a service The first step is to get the service to self-register. This is done by executing the QTfsListener.exe program with the -i switch. Navigate to the %programfiles%\varalogix directory with your command prompt and execute this command: QTfsListener.exe i 3. Establishing service account to run QTfsListener The account that the QTfsListener service runs under must have permissions to: 1. Subscribe to TFS Build Quality Status Change events. Either add the service account as a member of the Team Project Collection Administrators group, or grant the permission directly via the command line, for example: tfssecurity.exe /a+ EventSubscription $SUBSCRIPTION: CREATE_SOAP_SUBSCRIPTION n:yourdomain\yourqtfslisteneraccount ALLOW /collection: 2. Listen on the configured HTTP endpoint. This can be configured via the built-in "netsh" command, for example: netsh http add urlacl url= user=yourdomain\ YourQTfsListenerAccount 3. Edit Build Quality events. Add the EditBuildQuality permission for the Domain\Account account on the Team Collection. This can be added directly via the command line, for example: tfssecurity.exe /a+ EditBuildQuality n:domain\account ALLOW /collection: The firewall must also be configured to allow inbound connections on the listening port. For the Windows Firewall, this can also be configured via the built-in "netsh" command, for example: netsh advfirewall firewall add rule name="qtfslistener Service" dir=in action=allow protocol=tcp localport=8881 remoteip=localsubnet profile=domain 4. Edit configuration settings Before starting the service, review the settings in the QTfsListener.exe.config configuration file. The relevant settings are: Page 4 of 7

5 TeamProjectCollectionUri: the address of TFS Team Project Collection for which QTfsListener will subscribe to events. BaseAddress: the address that Team Foundation Server will use to contact this QTfsListener instance. This address must be resolvable from the Team Foundation Server machine so localhost is not applicable (unless QTfsListener is installed on the same machine as the Team Foundation Event Service). QAPIHost: the address of a computer running the VaraLogix Q API service. QTfsListener will use this host to create the Q Package Instance. QAuth: a valid Q authentication string. Either a Q Authentication token from Q, or a username and password separated with a space. TfsUserName, TfsDomain and TfsPassword: optional. Only specified if QTfsListener should authenticate with the Team Foundation Server using credentials different from the service account. These options are useful for debugging. 5. Edit the Qmappings.xml file The Qmappings.xml file maps a Build Quality Change event to a Q package instance. Below is a sample Qmappings.xml file. <DeploymentMappings xmlns=" <Mapping BuildDefinitionPattern="BuildDef 1" Computer="*" OriginalQuality="*" NewQuality="Ready for Deployment" SuccessQuality="Q Deploy Processing" FailureQuality="Q Send Failure" QPackage="Sample File Deploy Project 1" QRoute="Sample File Deploy Route 1" DeployInstance="true" /> <Mapping BuildDefinitionPattern="BuildDef 2" Computer="*" OriginalQuality="*" NewQuality="Ready for Deployment" SuccessQuality="Q Deploy Processing" FailureQuality="Q Send Failure" QPackage="Sample File Deploy Project 2" QRoute="Sample File Deploy Route 2" DeployInstance="true" /> </DeploymentMappings> The Qmappings.xml file contains multiple mapping blocks. Each block corresponds to an Event a Q package instance. The fields of the Mapping tag are: Page 5 of 7

6 BuildDefinitionPattern Corresponds to a TFS project build definition. Computer Corresponds to the specific computer on which the TFS build was performed. This value may be the wildcard, *, to reference any computer. OriginalQuality Corresponds to the Build Quality before the Build Quality was changed. This allows the mapping to respond to a specific Build Quality transition. This value may be a wildcard. NewQuality Corresponds to the new Build Quality. This value may be a wildcard. SuccessQuality (optional). This value specifies a Build Quality which QTfsListener should set following a successful Q package instance creation. If this value is not present, the quality will not be changed. FailureQuality (optional). This value specifies a Build Quality which QTfsListener should set following a failure to create a Q package instance. If this value is not present, the quality will not be changed. QPackage This value specifies the Q package to use when creating a Q package instance. QRoute This value specifies the Q route to use when creating a Q package instance. DeployInstance This value indicates whether the Q package instance should be deployed automatically during Q package instance creation. 6. Configuring and starting the QTfsListener service 1. Open the Services management console (eg Start > Run > services.msc). 2. Locate and double-click the QTfsListener service. 3. Select the Log On tab in the Properties dialog. 4. Enter the username and password of the chosen QTfsListener service account (from section 3 above). 5. Click Ok. 7. Start the QTfsListener service At this point in time QTfsListener will connect to Team Foundation Server and subscribe to all build quality indicator change notifications. 8. Troubleshooting 1. Stop the QTfsListener service. 2. Open a Command Prompt using the QTfsListener service account credentials (ie run as) 3. Execute: TfsDeployer.exe d This will run QTfsListener on the console with more visibility as to whether the service is successfully subscribing to TFS events and receiving the notifications. Enable Tracing: You can enable tracing by un-commenting the trace switch at the bottom of the config file. <system.diagnostics> <switches> <add name="varalogix.utility.teamfoundation.common" value="verbose" /> <add name="qtfslistener" value="verbose" /> </switches> <trace autoflush="true" /> Page 6 of 7

7 </system.diagnostics> You can adjust the value of the switches to adjust the verbosity of the detail returned. Click here to learn more about the switches. The valid values for the switches are: Enumerated value Integer value Type of message displayed (or written to a specified output target) Off 0 None Error 1 Only error messages Warning 2 Warning messages and error messages Info 3 Informational messages, warning messages, and error messages Verbose 4 Verbose messages, informational messages, warning messages, and error messages Page 7 of 7