TFS Integration Platform – What Are Addins? Q&A-31

  • Article

2010-06-09 - Updated the list of addins after a refactor of the franework consolidated some and introduced a new one. Please refer to the TFS Integration Platform documentation, especially Configuration, for the latest information and configuration options for these add-ins.

Looking at an outdated sample configuration file, we will notice new tags, attributes and elements highlighted in bold and italic. The configuration also contains obsolete add-ins and should not be used as a production example. See note above.

    1: <?xml version="1.0"?>
    2: <Configuration xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="https://www.w3.org/2001/XMLSchema" UniqueId="E72273F7-..." FriendlyName="AddTest">
    3:    <Providers>
    4:       <Provider ReferenceName="FEBC091F-..." FriendlyName="TFS 2010 VC Migration Provider"/>
    5:       <Provider ReferenceName="F2A6BA65-..." FriendlyName="ClearCase 2003 Provider"/>
    6:    </Providers>
    7:    <Addins>  
    8:      <Addin ReferenceName="61B591B5-FBC6-4ec6-85C6-89252EB20BCC" FriendlyName="SubTree Label AnalysisAddin" />  
    9:      <Addin ReferenceName="C04C074E-E193-4b18-8C6F-5B864C68D0B7" FriendlyName="ChangeGroup Comment AnalysisAddin" />  
   10:      <Addin ReferenceName="AC260D98-2411-4829-B4F7-D548F1BC8143" FriendlyName="Start Sync via Semaphore File AnalysisAddin" />  
   11:    </Addins>  
   12:    <SessionGroup FriendlyName="Session Group Friendly Name" SessionGroupGUID="2ef620e3-...">
   13:       <WorkFlowType Frequency="ContinuousManual" DirectionOfFlow="Unidirectional" SyncContext="Disabled"/>
   14:       <MigrationSources>
   15:          <MigrationSource InternalUniqueId="07ed1fe0-..." FriendlyName="CC Dynamic View" ServerIdentifier="ClearCase 7.1" 
   16:                           ServerUrl="\elements_vob" SourceIdentifier="feb04_view" ProviderReferenceName="F2A6BA65-...">
   17:             <CustomSettings>
   18:               <CustomSetting SettingKey="AnalysisAddin1" SettingValue="61B591B5-FBC6-4ec6-85C6-89252EB20BCC" />  
   19:               <CustomSetting SettingKey="AnalysisAddin2" SettingValue="C04C074E-E193-4b18-8C6F-5B864C68D0B7" />  
   20:               <CustomSetting SettingKey="PreAnalysisAddinName" SettingValue="AC260D98-2411-4829-B4F7-D548F1BC8143" />  
   21:               <CustomSetting SettingKey="SemaphoreFilePath" SettingValue="e:\MigrationSemaphoreAndMetadata.xml" />  
   22:             </CustomSettings>
   23:             <StoredCredential/>
   24:          </MigrationSource>
   25:          ...
   26:       </MigrationSources>
   27:       <Sessions>
   28:          ...
   29:       </Sessions>
   30:       <Linking>
   31:       </Linking>
   32:    </SessionGroup>
   33: </Configuration>

Addin Overview

The TFS Integration Platform architecture is based on a pipeline from one end-point to another, and adapters delivering specific features required during the analysis and migration phases of the pipeline processing. See the TFS Integration Platform – Architecture document and section TFS Integration Platform Pipeline for more information.

The adapters have to implement specific contracts and associated features, such as the generation of context information tables, delta tables and link deltas. If additional features are needed over time, we are faced with a common dilemma of adapters becoming all-encompassing, bulky, heavy and difficult to maintain.

The addin extension to the architecture ensures that adapter developers are able to decompose their adapters into smaller focused services, complementing existing adapters with additional features or special features such as tracing and auditing which may be common to one or more adapters.

The Addins can be targeting an adapter, as is the case with  the Start Sync via Semaphore File Analysis Addin or the TFS Active Directory User Id Lookup Service Addin we encountered in TFS Integration Platform – What is the Lookup Service? Q&A-27. Alternatively the Addins can target the platform itself, which introduced new hooks in the pipeline processing to allow addins to inject functionality pre or post processing as shown in the illustration below.

Some of the new hooks in the pipeline processing logic are highlighted in yellow, whereby I removed all trace and policy checking logic from the following “pseudo code”:

Addins that are targeting the Analysis phase of the pipeline are prefixed with the name AnalsysisAddIn* in the configuration and those targeting the Migration  phase with MigrationAddIn*, whereby we can inject one or more addins in the platform, giving us immense flexibility to develop  loosely coupled and tightly cohesive adapter and addins.

The extract from a sample configuration file above, shows (1) the declaration of three addins and (2) the injection of two addins in the Analysis phase and another into the adapter itself. The key difference between the first two and the third, is that the adapter is completely unaware of the former, whereas the latter is known and loaded by the adapter itself.

If you are interesting in building a custom addin, have a look at the mentioned addins in the codebase and take special note of the IAddIn interface, the MigrationAddIn and the AnalysisAddIn abstract classes.

  • IAddin … an interface that defines a mechanism for retrieving an Add-in service provider
  • AnalysisAddin … an abstract class that provides extensibility points for Addins to be written to extend the functionality of the AnalysisProvider portion of a TFS Integration Platform adapter
  • MigrationAddin … an abstract class that provides extensibility points for Addins to be written to extend the functionality of the MigrationProvider portion of a TFS Integration Platform adapter

Analysis Addin Hooks:

  • Pre Analysis
  • Post Change Group Delta Computation
  • Post Delta Computation
  • Post Generate Migration Instructions
  • Post Change Group Conflict Detection
  • Post Conflict Detection
  • Post Change Group Analysis
  • Post Analysis

Migration Addin Hooks:

  • Pre Migration
  • Post Change Group Migration
  • Post Migration

Addin Examples

Examples of Addins include:

Friendly Name

Reference Name

Description

ChangeGroup Label Analysis Addin

356F2115-223D-46d5-90BF-3027EEAA271B

The ChangeGroup Label AnalysisAddin is optionally configured with the source side of a version control migration or sync and generates migration instructions to create a label on the target side of the migration. The resulting label on the target side will label all folders and files that were modified in the process of migrating that change group (with the exception of deleted items). A label name will be automatically generated that includes identifies the Change Group on the source side as well as the date and time.

File Properties Analysis Addin (Sample)

A745F890-162F-40f4-A445-A0DFBEBF1A1A

Implementation of an Addin that add file level property metadata to files added or changed in a ChangeGroup.

This is a sample of AnalysisAddin for the source side of a version control migration or sync that generates migration instructions to add properties to the files and folders on the target side of the migration.

This sample adds two properties to each folder and file changed in each ChangeGroup migrated (except for deleted items) with the following names:

· SourceChangeGroupIdThe Id of the ChangeGroup on the source side that resulted in the change on the target side.

· SourceChangeGroupOwnerThe owner of that ChangeGroup on the source side (typically the user that performed the check-in)

Note that the target side version control system must support file properties (sometime named "attributes") for this Addin to be useful. TFS 2010 and ClearCase are two version control systems that provide this support. TFS 2008 does not.

Semaphore File Analysis Addin

AC260D98-2411-4829-B4F7-D548F1BC8143

The SemaphoreFileAnalysisAddin is used with version control adapters like the File System adapter. This add-in is intended to be used as part of an integration solution where a file on disk provides three key capabilities in the version controlsync pipeline:

1) Gating the flow of changes from disk (the file system) to TFS based on last modified/created time.

2) Providing changeset comment metadata.

3) Providing label metadata.

Taken together, this add-in enables the FileSystem adapter to be used in a setting where something like a nightly build or other automated process pulls a whole buildable tree to disk. Once the tree is in a known good state, as at the end of a build, process automation kicks in and writes aggregate comment and label metadata into the configured semaphore file. The change in the timestamp on the semaphore file triggers the flow of information into TFS with Comment and Label information inside the file used to decorate the changeset.
TFS 2010 User Id Lookup Addin CDDE6B6B-72FC-43b6-BBD1-B8A89A788C6F

 
ClearCase SymbolicLink Monitor AnalysisAddin 7AF45F88-7D99-48F2-9B15-673E619B5ED8

An AnalysisAddin that can be used with the ClearCaseSelectedHistoryAdapter to create a file based on the list of symbolic links found in the VOBs referenced when migrating/syncing from ClearCase to TFS. The output file will contain one line with the path of a TFS item that corresponds to a symbol link in ClearCase.

The output file path can be configured using a CustomSetting with the key name "SymbolLinkOutputFilePath". If that key is not present, the output filename defaults to "ClearCaseSymbolLinksMigrated.txt" in the current working directory.

These adapters are default implementations of Addins that provides a comment for a change group, provides a label for a change group, adds a label for a change group, adds file level property metadata to files added or changed in a ChangeGroup, and provides label information for use by the file system adapter.


The illustration above shows the basic breakdown of the ChangeGroup Comment Analysis Addin.

Refer to the “TFS integration Platform – Configuration” documentation, which will appear in the next drop of the TFS Integration Platform, for an overview of the configuration of these adapters.


Why are we still seeing architecture changes?

Please be aware that the current TFS Integration Platform is still in “Alpha” release state and therefore breaking interface changes and new powerful features, such as the Addins, will make an appearance and could potentially impact you custom development targeting the current TFS Integration Platform. The team is still hardening down the platform and the adapters, such as TFS, ClearQuest and ClearCase, and working hard to ensure that we can soon switch from ALPHA to BETA, after which the dust will settle :)