Notes on Team Foundation Server

This page covers the fine-print how AbaPerls accesses Team Foundation Server.

Contents:
   How AbaPerls Accesses Team Foundation Server
   TFS and Version Specifications
   Characteristics of Labels in TFS

How AbaPerls Accesses Team Foundation Server

AbaPerls accesses TFS through its .Net API. The assemblies for this API is bundled into the Perl installation needed to run AbaPerls.

This API is installed when you install Visual Studio 2010 or Team Explorer 2010. Once they are installed, you should have no problems accessing the API. Or least so I believe. Please observe that you cannot use versions of the API that comes with earlier or later versions of Visual Studio.

When you access TFS through Team Explorer in Visual Studio or the TF command-line tool, you need to have a workspace defined. AbaPerls uses the workspaces only when it fits its purposes, and you in theory you could use AbaPerls with TFS without have any workspaces set up. However, this would not be a smart thing to do, because:

If AbaPerls can map your current disk directory to a directory in TFS, and you don't specify the ‑VC option (and nor the ‑config option with DBBUILD and DBUPDGEN), AbaPerls will use the TFS directory as the VC-path. If the TFS path includes /SQL, AbaPerls strips /SQL and everything that comes after it. Say that your current directory is C:\Dev\My Project\2.10\Subsys1\SQL\SP, and in the TFS Server TFSRV you have mapped $/Projects/My Project to C:\Dev\My Project. AbaPerls will set the VC-path to TFSSRV/$/Projects/My Project/2.10/Subsys1.

This is possible, thanks to that TFS tracks your path mappings manually, and does not permit you to map the same folder to different project collections or servers.

Caveat: the above will not work, if you only work in a version of Visual Studio that was not released when the version of AbaPerls you are using was packaged, as AbaPerls needs assemblies specific to the VS version to perform this lookup.

If you for some reason do not want this automatic mapping, there is currently no provision to decline. You would either have to copy the files somewhere else, or remove the path mapping in TFS.

Another situation when AbaPerls is interested in your workspaces is when you specify a VC-path, but leaves out the repository part and only have one workspace registered on the computer, AbaPerls take the repository from this workspace.

When you use the tool SSREPLACE, you need to have a workspace, since it is not possible to check out files in TFS without a workspace.

A completely different situation is when you use the ‑get option with ABASQL, DBBUILD or update scripts created by DBUPDGEN, AbaPerls puts the file as mandated by its own rules. In this case, AbaPerls checks that your current folder does not map to a directory in TFS. (To save you from the confusion that could arise, if ‑VC is set implicitly when you don't want to.)

TFS and Version Specifications

There are several places in AbaPerls where you can specify a version for a directory or a file, either with the ‑label option (ABASQL, DBBUILD or DBUPDGEN) or as an argument (LISTCONFIG or a config-file). The command-line tool TF has some conventions to specify versions. AbaPerls supports these conventions, but changes the rules a bit to promote its own label convention. In order, the following applies.

If you specify T or LATEST, this means the most recently checked-in version.
If you have a string which consists of digits only, this is taken as a changeset number. The way TFS works, it will give you the version of a file that was current when that changeset was checked in, even if the file was not part of the changeset.
If the string matches the AbaPerls label convention of LetterMajor.Middle.Minor it is a label, even if the letter is one of letters that has a special meaning for TF.
If .Net can parse the string as a datetime value, it is a date.
If the string starts with C, the rest of the string is assumed to be a changeset number, just as with TF, and you get an error if the string is not a number.
If the string starts with D, the rest of the string is assumed to be a datetime value, just as with TF, and you get an error if the string is not.
If the string starts with L, the rest of the string is interpreted as a label, just as with TF.
If no other rule applies, the string is taken as a label.

Users of TF may know that TF also uses the latter W to denote the workspace version. Since AbaPerls don't deal with workspaces, AbaPerls does not give any certain meaning to an initial W.

Characteristics of Labels in TFS

Labels in TFS are very different from labels in SourceSafe. While a label in SourceSafe reflects a snapshot in time, which you can modify only marginally, labels in TFS are intended to be very elastic. Once you have set a label, you can alter which version of an individual files that goes into a label, and you can add or remove files from the label entirely. Presumably, this is why TFS finds the original date of the label so uninteresting that TFS does not even track that date. TFS only tracks when the label was most recently modified. This is also the date you see for the labels when you look at the Labels tab in the History screen in Source Control Explorer.

That flexibility is welcome, but there are still situations when AbaPerls wants to associate a label with a point in time. Specifically, when you use a config-file with DBBUILD or DBUPDGEN, AbaPerls wants to find the label that was the most recently created at a certain point in time. To make this possible with TFS, AbaPerls offers the tool NEWLABEL which creates a label according to the AbaPerls label convention. When you use NEWLABEL with TFS, NEWLABEL adds the current time as a comment to the label.

Another characteristic of TFS labels is that they have a scope, which does not necessarily agree with the directory where you applied the label. For instance, if you use Team Explorer to set the label L4.10.0050 on $/TeamProj/4.10/Subsys1 and subsequently try to set the same label on $/TeamProj/4.10/Subsys2, you will be told that the label already exists. This is because the scope for a label which you set in Team Explorer is always the team project. To set a label with a different scope, you need to use TF. Unless you want to set an AbaPerls label – in this case you should use NEWLABEL. In case you mistakenly set an AbaPerls label with Team Explorer, you can repair it with TFSLABELFIX. If there is no timestamp in the comment for the label, TFSLABELFIX will add that to the comment, using the time the label most recently was modified (as this is the only timestamp that TFS offers).