Team Foundation Server Integration

Applies to Collaborator 14.6, last modified on November 06, 2024

Collaborator seamlessly integrates with the Team Foundation Server (TFS) version control system and its successor Azure DevOps Server. This section provides a general overview of integration preferences, ways to review files controlled by TFS, and so on.

About Integration

Using the built-in Collaborator TFS integration, you can quickly upload various files to the Collaborator server to create a review directly from the desktop client of your choice. The types of files you can upload include:

  • Files controlled by Team Foundation Server.
  • Shelvesets.
  • Changesets.

TFS integration uses TFS client applications that are already installed on the client computer. That is, integration supports all protocols, authentication settings, proxies, and other configuration specifics.

Supported Versions

To enable the integration via GUI Client and Command-Line Client, we use Team Foundation Server SDK to communicate with Team Foundation Server. Team Foundation Server and Azure DevOps Server versions 2010 through 2020 are supported.

Ways of Integration

You can enable the integration between Collaborator and TFS for GUI Client or Command-Line Client

GUI Client

To enable the integration:

  1. Start GUI Client.

  2. Click Add to create a new SCM configuration.

  3. In the subsequent SCM Configuration dialog, specify the local source code location. Then, select Team Foundation Server in the SCM drop-down list.

  4. TFS Configuration
    You may choose to skip setting these options. In this case, these parameters will be set as defined in the environment.
    TFS Collection URL For self-hosted version of Team Foundation Server, specify the URL of Team Foundation Project Collection to work with, for instance: http://tfs.acme.com/my-collection
    For SaaS version of Team Foundation Server, specify the URL of your Visual Studio Team Services account (without project or collection names), for instance: http://jsmith-ts.visualstudio.com
    TFS User The name of Team Foundation user.
    TFS Personal Access Token The personal access token of the user. For detailed information on generating a personal access token, follow Microsoft documentation.

  5. Once ready, click Validate to make sure the integration is operational.

After that, a new configuration for TFS will appear on the main screen of the GUI Client.

Select it, then click on the corresponding button depending on what you want to do next:

Buttons for TFS files uploading

  • Add Changes – Upload modified files from the TFS workspace to the Collaborator server and add them to a review.

    Add Changes

  • Add Shelvesets – Upload files in a shelveset to the Collaborator server and add them to a review.

    Add Shelvesets

    If you want to upload a shelveset that does not belong to your list of shelvesets, use Add Changesets.

  • Add Changesets – Upload files in a changeset to the Collaborator server and add them to a review.

    Add Changesets

    In the dialog, you can select whether you want it to display all available changesets, input IDs of specific changesets, changelists within a specific range or data interval.

Command-Line Client

In the Command-Line Client, you can create a review for changes you have applied locally to files controlled by TFS – before uploading these to the version control repository.

Commands recommended for Team Foundation Server

ccollab addchanges - Attaches locally-modified files to a review.

ccollab addchangelist - Attaches an atomic changelist to a review.

ccollab commit - Commit changes in the review.

The addchanges command will upload local changes to files controlled by Team Foundation before they are checked in.

The addchangelist command will upload the files in a shelveset or changeset.

In most cases, the Command-Line Client can automatically detect your Team Foundation configuration. Try testing your configuration to verify the configuration is detected correctly.

If the Command-Line Client is unable to detect your Team Foundation configuration or you want to override the detected settings, you can manually specify Team Foundation settings using global options.

To manually configure the Command-Line Client to use Team Foundation, execute the following command:

Team Foundation Server-specific Options

Option

Description

--tfs-collection <value>

For self-hosted version of Team Foundation Server, specify the URL of Team Foundation Project Collection to work with.

For SaaS version of Team Foundation Server, specify the URL of your Visual Studio Team Services account (without project or collection names).

--tfs-user <value>

The name of Team Foundation user.

--tfs-passwd <value>

The personal access token of the user. For detailed information on generating a personal access token, follow Microsoft documentation.

Collaborator provides special triggers that fire when someone submits files to a folder that is controlled by a gated check-in process in Team Foundation Server. These triggers are listed in the table below.

Trigger Description
ensure-review-started Ensures that a review has been started (created in Collaborator) for the submitted changelist.
ensure-completed Ensures that a review has been completed for the submitted changelist.

These triggers ensure that files cannot be submitted unless a review for the respective changelist has been started (or completed). If the conditions are met, the commit will be allowed to continue normally.

These triggers work for Microsoft Team Foundation System 2018, 2017, 2015 and 2013. Currently, Update 1 and Update 1 Release 2 of Team Foundation System 2015 are not supported.

The triggers are implemented by dynamic-link libraries that you can download from the SmartBear web site as a .zip archive:

https://support.smartbear.com/downloads/collaborator/installers-for-collaborator-14/

Install triggers

To install the triggers you will need to perform the following steps:

  1. Download the .zip archive from the page mentioned above and unpack it to some folder on your computer. The archive includes the dlls folder that have the dynamic-link libraries for the supported Visual Studio versions. Also, the archive includes a README file with instructions similar to those you can see below.

  2. Open the <Team Foundation Server>\Application Tier\Web Services\web.config file and append the following lines to the <appSettings> section:

    <appSettings>
    ...
    <!-- The following settings are for Collaborator triggers -->
    <!-- Required setting -->
    <add key="collab:serverUrl" value="http://yourcollabserver:port" />
    <!-- Required setting -->
    <add key="collab:userName" value="collabUser" />
    <!-- Required setting. For an empty password, use value="" -->
    <add key="collab:userPassword" value="collabPassword" />
    <!-- Optional setting. Default is "started" -->
    <add key="collab:triggerType" value="completed" />
    ...
    </appSettings>

  3. Copy the following DLLs from the unpacked dlls\<Your-Visual-Studio-version> folder to the <Team Foundation Server>\Application Tier\Web Services\bin\Plugins folder:

    • collab-ensure-review-started-or-completed.dll 
    • log4net.dll 
    • Newtonsoft.Json.dll 

To use the triggers, you must require developers to put the review ID somewhere in the TFS commit message. The review ID must be specified in the Review: NNN format, where NNN stands for review number. Here is an example:

Commit message example:
TFS: Add support for gated check-ins (Review: 12345)

Collaborator uses the (@"Review:*\s?(\d+)") regular expression to extract the review id from the commit information. This text can appear inline with other text or in a more formal form-style layout.

Troubleshooting

If you run across any issues or problems, it will help SmartBear technical support if you send in a debugging log. To capture a debugging log:

  1. Open <Team Foundation Server>\Application Tier\Web Services\web.config file and append the following lines to the <configSections> section:

    <configSections>
    ...
    <!-- The following setting is for debugging Collaborator triggers -->
    <section name="log4net" type="log4net.Config.Log4NetConfigurationSectionHandler, log4net"/>
    ...
    </configSections>

  2. Also append the the following section to the web.config file:

    <log4net debug="true">
    <appender name="LogFileAppender" type="log4net.Appender.FileAppender">
    <param name="File" value="C:/temp/collab_TFS_GatedCheckIn.log" />
    <param name="AppendToFile" value="true" />
    <layout type="log4net.Layout.PatternLayout">
    <param name="Header" value="[Header]\r\n" />
    <param name="Footer" value="[Footer]\r\n" />
    <param name="ConversionPattern" value="%d [%t] %-5p %c %m%n" />
    </layout>
    </appender>
    <root>
    <level value="DEBUG" />
    <appender-ref ref="LogFileAppender" />
    </root>
    </log4net>

    The above settings will generate the debugging log file at specified path.

  3. Replace the DLLs in the Plugins folder with their fresh copy. This will force TFS to re-read the web.config file.

You may adjust the log output data for your needs by changing the above settings according to log4net convention of configuration files.

Remarks

Additionally to version control integration with Team Foundation Server, you can enable integration with TFS work items. This will allow synchronizing reviews and work items addressed in that reviews, appending the issues to the Remote System Links section of the review and retrieving the current status of the item. See Issue-Tracking Integrations: Overview for more information.

The Team Foundation Server integration will not work with non-English installations of Visual Studio .NET. Regional settings for other locales are supported, but installing a non-English Visual Studio prevents correct parsing of the TF command line output.

When using Team Explorer Everywhere clients, our client will need access to the server for changelist information without being prompted for a password. To do this you will need to save your login information to your credentials cache using the TF_AUTO_SAVE_CREDENTIALS environment variable, which is documented here. Once you have set this you will need to use a mutating command (such as checkout, checkin, and so on) and enter your credentials one more time for it to stick.

Technical Details and Limitations

Review Screen, Diff Viewer, Eclipse Plug-in and Visual Studio Extension display atomic changelists (changesets in terms of TFS) in chronological order (from older to newer), regardless the order in which they have been uploaded to review.

Collaborator does not guarantee that Diff Viewer will display correct comparison results for the following cases:

  • If you have "gaps" while adding subsequent atomic changelists (changesets in terms of TFS) to the same review. For example, add changelists 1, 2, and 4, but forget to add changelist 3.

  • If you add pending changelists from different workspaces to the same review.

  • If you add several diffs (non atomic changelists) to the same review.

See Also

SCM Configuration
ccollab set
Source Control Integrations

Highlight search results