But it works on my PC!

The random thoughts of Richard Fennell on technology and software development

Why have I got a ‘.NETCore50’ and a ‘netcore50’ folder in my nuget package?

I recently posted on how we were versioning our Nuget packages as part of a release pipeline. In test we noticed that the packages being produced by this process has an extra folder inside them.

image 

We expected there to be a netcore50 folder, but not a .NETCore50 folder. Strangely if we build the package locally we only saw the expect netcore50 folder. The addition of this folder did not appear to be causing any problem, but I did want to find out why it had appeared and remove it as it was not needed.

Turns out the issue was the version of Nuget.exe, the automatically installed version on the on-prem TFS build agent was 3.2, my local copy 3.4. As soon as I upgraded the build box’s nuget.exe version to 3.4 the problem went away

Experiences versioning related sets of NuGet packages within a VSTS build

Background

We are currently packaging up a set of UX libraries as NuGet packages to go on our internal NuGet server. The assemblies that make up the core of this framework are all in a single Visual Studio solution, however it makes sense to distribute them as a set of NuGet packages as you might not need all the parts in a given project. Hence we have a package structure as follows…

  • BM.UX.Common
  • BM.UX.Controls
  • BM.UX.Behaviours
  • etc…

There has been much thought on the versioning strategy of these packages. We did consider independent versioning of each of these fundamental packages, but decided it was worth the effort, keeping their versions in sync was reasonable  i.e. the packages have the same version number and are released as a set.

Now this might not be the case for future ‘extension’ packages, but it is an OK assumption for now, especially as it makes the development cycle quicker/easier. This framework is young and rapidly changing, there are often changes in a control that needs associated changes in the common assembly; it is hence good that a developers does not have to check-in a change on the common package before they can make an associated changed to the control package whist debugging a control prior to it being released.

However, this all meant it was important to make sure the package dependencies and versions are set correctly.

Builds

We are using Git for this project (though this process is just as relevant for TFVC) with a development branch and a master branch. Each branch has its own CI triggered build

  • Development branch build …
    • Builds the solution
    • Runs Unit tests
    • Does SonarQube analysis
    • DOES NOT store any built artifacts
    • [Is used to validate Pull requests]
  • Master branch build …
    • Versions the code
    • Builds the solution
    • Runs Unit tests
    • Creates the NuGet Packages
    • Stores the created packages (to be picked up by a Release pipeline for publishing to our internal NuGet server)

Versioning

So within the Master build we need to do some versioning, this needs to be done to different files to make sure the assemblies and the NuGet packages are ‘stamped’ with the build version.

We get this version for the build number variable, $(Build.BuildNumber), we use the format $(Major).$(Minor).$(Year:yy)$(DayOfYear).$(rev:r)  e.g. 1.2.16123.3

Where

  • $(Major) and $(Minor) build variables we manage (actually our release pipeline updates the $(Minor) on every successful release to production using a VSTS task)
  • $(Year:yy)$(DayOfYear) gives a date in the form 16123
  • and $(rev:r) is a count of builds on a given day

We have chosen to use this number format to version both the assemblies and Nuget packages, if you have different plans, such as semantic versioning , you will need to modify this process a bit.

Assemblies

The assemblies themselves are easy to version, we just need to set the correct value in their assemblyinfo.cs or assemblyinfo.vb files. I used my Assembly versioning VSTS task to do this

NuGet Packages

The packages turn out to be a bit more complex. Using the standard NuGet Packager task there is a checkbox to say to use the build number as the version. This works just fine versioning the actual package, adding the –Version flag to the package command to override the value in the project .nuspec file. However it does not help with managing the versions of any dependant packages in the solution, and here is why. In our build …

  1. AssemblyInfo files updated
  2. The solution is built, so we have version stamped DLLs
  3. We package the first ‘common’ Nuget package (which has no dependencies on other projects in the solution) and it is versioned using the –version setting, not the value in it’s nuspec file.
  4. We package the ‘next’ Nuget package, the package picks up the version from the –version flag (as needed), but it also needs to add a dependency to a specific version of the ‘common’ package. We pass the –IncludeReferencedProjects  argument to make sure this occurs. However, Nuget.exe gets this version number from  the ‘common’ packages .nuspec file NOT the package actually built in the previous step. So we end up with a mismatch.

The bottom line is we need to manage the version number in the .nuspec file of each package. So more custom VSTS extensions are needed.

Initially I reused my Update XML file task, passing in some XPath to select the node to update, and this is a very valid approach if using semantic versioning as it is a very flexible way yo build the version number. However, in the end I added an extra task to my versioning VSTS extension for Nuget to make my build neater and consistent with my other versions steps.

Once all the versioning was done I could create the packages. I ended up with a build process as shown below

image

A few notes about the NuGet packaging

  • Each project I wish to create a Nuget package for has a nuspec file of the same ‘root’ name in the same folder as the csproj eg. mypackage.csproj and mypackage.nuspec. This file contains all descriptions, copyright details etc.
  • I am building each package explicitly, I could use wildcards in the ‘Path/Pattern to nuspec files’ property, I choose not to at this time. This is down to the fact I don’t want to build all the solution’s package at this point in time.
  • IMPORTANT I am passing in the .csproj file names, not the .nuspec file names to the ‘Path/Pattern to nuspec files’ property. I found I had to do this else the   –IncludeReferencedProjects  was ignored. The Nuget documentation seems to suggest as long as the .csproj and .nuspec files have the same ‘root’ name then you could reference the .nuspec file but this was not my experience
  • I still set the flag to use the build version to version the package – this is not actually needed as the .nuspec file has already been update
  • I pass in the  –IncludeReferencedProjects  argument via the advanced parameters, to pick up the project dependancies.

Summary

So now I have a reliable way to make sure my NuGet packages have consistent version numbers 

Tidy up those VSTS release pipelines with meta-tasks

Do you have repeating blocks in your VSTS release pipelines?

I certainly do. A common one is to run a set of functional test, so I need to repeatedly …

  1. Deploy some test files to a VM
  2. Deploy a test agent to the VM – IMPORTANT I had not realised you can only run one test run against this deployed agent. You need to redeploy it for the next run
  3. Run my tests
  4. … and repeat for next test type/configuration/test plan/DLL etc.

 

In the past this lead to a lot of repeat tasks in my release pipeline, all very messy.

Now in VSTS we have the option of  Meta-tasks, these allow tasks to be grouped into in-effect functions with their own properties.

 

image

In the above screen shot below you can see I use a meta-task ‘Run Tests’ that wrappers the four tasks shown below.

image

Much neater, but as you might expect with something new I have come across a few minor gotchas

  • You cannot order the list of properties for the meta-task
  • This is a problem as the first one is used to generate the instance name in the pipeline. No a major problem you can always edit it.
  • Meta-tasks properties are auto-detected from any variables used with in the meta-task tasks, the auto-detection mechanism is case sensitive, unless the rest of VSTS variable handling. So be careful to not end up with duplicates.

That all said, I think this is big step forward in readability and reuse for release management

New version of my generate release notes task–now with authentication options

I have just released 1.4.7 of the release notes VSTS extension. This provides a new advanced options that allows you to switch the authentication model.

The default remains the same i.e. use a personal access token provided by the server, but you have the option to enable use of the 'defaultcredentials' (via the advanced properties). If this is done the account the build agent is running as is used. Hopefully this should fix the 401 issues some people have been seeing when using the task with on-prem TFS.

For most people the default PAT model should be fine

New Build Management VSTS tasks

Just published a new VSTS extension with a couple of tasks in it. The aim to to help formalise the end of a release process. The tasks

  • Allow you to set the retension ‘keep forever’ flag on a build (or all builds linked to a release)
  • Update increment a build variable e.g. all or part of a version number, in a build (or all builds linked to a release)

The first just replicates functionality I used to have in house for builds

The second one is important to me as once I have released to production a version of a product I never want to generate another build with the same base version number. For example we version stamp all our DLLs/builds with a version number in form

$(Major).$(Minor).$(year:yy)$(dayofyear).(rev:r)     e.g. 1.2.16170.2

Where the $(Major) and $(Minor) are build variables we set manually (we decide when we increment a major or minor release) and the second two blocks guarantee a unique build number every time. It is too easy to forget to manually increment the Major or Minor build variable during a release. This task means I don’t need to remember to set the value of one or both of these. I can either set an explicit value or just get it to auto-increment. I usually auto increment the Minor value as a default, doing a manual reset of both the Major and Minor if it is a major release.

NOTE: You do have to add some permissions to the build service account else this second task fails with a 403 permission error – so read the WIKI

Gotcha’s when developing VSTS Build Extension

I recently posted on my development process for VSTS Extensions, it has been specifically PowerShell based build ones I have been working on. During this development I have come across a few more gotcha’s that I think are worth mentioning

32/64 bit

The VSTS build agent launches PowerShell 64bit (as does the PowerShell command line on dev PC), but VSCode launches it 32bit. Whilst working my StyleCop extension this caused me a problem as StyleCop it seems can only load dictionaries for spell checking based rules when in a 32bit shell. So my Pester tests for the extension worked in VSCode but failed at the command line and within a VSTS build

After many hours my eventual solution was to put some guard code in my scripts to force a reload in 32bit mode

param
(
    [string]$treatStyleCopViolationsErrorsAsWarnings,
    [string]$maximumViolationCount,
    … other params
)

if ($env:Processor_Architecture -ne "x86")  
{
    # Get the command parameters
    $args = $myinvocation.BoundParameters.GetEnumerator() | ForEach-Object {$($_.Value)}
    write-warning 'Launching x86 PowerShell'
    &"$env:windir\syswow64\windowspowershell\v1.0\powershell.exe" -noprofile -executionpolicy bypass -file $myinvocation.Mycommand.path $args
    exit
}
write-verbose "Running in $($env:Processor_Architecture) PowerShell"

... rest of my code

 

The downside of this trick is that you can’t pass return values back as you swapped execution process. For the type of things I am doing with VSTS tasks this not an issue as the important data has usually be dropped to a file which is accessible by everything, such as test results.

For a worked sample of production code and Pester tests see by GitHub repo.

Using Modules

In the last post I mentioned the problem when trying to run Pester tests against scripts, the script content is executed. I stupidly did not mention the obvious solution of moving all the code into functions in a PowerShell modules. This makes it easier to write tests for all bar the outer wrapper .PS1 script that is called by the VSTS agent.

Again see by GitHub repo so a good sample. Note how I have split out the files so that I have

  • A module that contains the functions I can test via Pester
  • A .PS1 script called by VSTS (this will run 64bit) where I deal with interaction with VSTS/TFS
  • An inner PS1 string that we force into 32bit mode as needed (see above)

Hacking around on your code

You always get to the point I find when developing things like VSTS build tasks that you want to make some quick change to try something without the full development/build/release cycle. This is in effect the local development stage, it is just build task development makes with awkward. It is hard to fully test a task locally, it need to be deployed within a build

I have found a way to help here is to use a local build agent, you can then get at the deployed task and edit the .PS1 code. The important bit to node is that the task will not be redeployed so you local ‘hack’ can be tested within a real TFS build without having to increment the task’s version and redeploy.

Hacky but handy to know.

You of course do need to make sure you hacked code is eventually put through your formal release process.

And maybe something or nothings…

I may have seen these issues, but have not got to the bottom of them, so they may not be real issues

  • The order parameters are declared in a task.json file seems to need to match the order they are declared in the .PS1 file call. I had thought they we associated by name not order, but in one task they all got transposed until I fixed the order.
  • The F5 dev debug cycle is still a little awkward with VSCode, sometime it seems to leave stuff running and you get high CPU utilisation – just restart the VSCode  - the old fix!
  • If using the 32 bit relaunch discussed above write-verbose messages don’t awlays seem to show up in the VSTS log, I assume a –verbose parameter is being lost somewhere, or it is the spawning of another PowerShell instance that cause the problem.

SO again I hope these tips help with your VSTS extension development

Running TSLint within SonarQube on a TFS build

I wanted to add some level of static analysis to our Typescript projects, TSLint being the obvious choice. To make sure it got run as part of our build release process I wanted to wire it into our SonarQube system, this meant using the community TSLintPlugin, which is still pre-release (0.6 preview at the time of writing).

I followed the installation process for plugin without any problems setting the TSLint path to match our build boxes

C:\Users\Tfsbuild\AppData\Roaming\npm\node_modules\tslint\bin\tslint

Within my TFS/VSTS build I added three extra tasks

image

  • An NPM install to make sure that TSLint was installed in the right folder by running the command ‘install -g tslint typescript ‘
  • A pre-build SonarQube MSBuild task to link to our SonarQube instance
  • A post-build SonarQube MSBuild task to complete the analysis

Once this build was run with a simple Hello World TypeScript project, I could see SonarQube attempting to do TSLint analysis but failing with the error

2016-07-05T11:36:02.6425918Z INFO: Sensor com.pablissimo.sonar.TsLintSensor

2016-07-05T11:36:07.1425492Z ##[error]ERROR: TsLint Err: Invalid option for configuration: tslint.json

2016-07-05T11:36:07.3612994Z INFO: Sensor com.pablissimo.sonar.TsLintSensor (done) | time=4765ms

The problem was the build task generated sonar-project.properties file did not contain the path to the TSLint.json file. In the current version of the TSLint plugin this file needs to be managed manually, it is not generated by the SonarQube ruleset. Hence is a file in the source code folder on the build box, a path that the SonarQube server cannot know.

The Begin Analysis SonarQube for MSBuild task generates the sonar-project.properties, but only adds the entries for MSBuild (as its name suggests). It does nothing related to TsLint plugin or any other plugins.

The solution was to add the required setting via the advanced properties of the Begin Analysis task i.e. point to the tslint.json file under source control, using a build variable to set the base folder.

/d:sonar.ts.tslintconfigpath=$(build.sourcesdirectory)\tslint.json

image

Once this setting was added I could see the TSLint rules being evaluated and the showing up in the SonarQube analysis.

Another step to improving our overall code quality through consistent analysis of technical debt.

Scroll bars in MTM Lab Center had me foxed – User too stupid error

I thought I had a problem with our TFS Lab Manager setup, 80% of our environments had disappeared. I wondered if it was rights, was it just showing environments I owned? No it was not that.

Turns our the issue was a UX/Scrollbar issue.

I had MTM full screen in ‘Test Center’ mode, with a long list of test suites, so long a  scroll bar was needed and I had scrolled to the bottom of the list

I then switched to ‘Lab Center’ mode, this list was shorter, not needing a scrollbar, but the the pane listing the environments (that had been showing the test suites) was still scrolled to the bottom. The need for the scrollbar was unexpected and I just missed it visually (in my defence it is light grey on white). Exiting and reloading MTM had no effect, the scroll did not reset on a reload or change of Test Plan/Team Project.

In fact I only realised the solution to the problem when it was pointed out by another member of our team after I asked if they were experiencing issues with Labs; the same had happened to them. Between us we wasted a fair bit of time on this issue!

Just goes to show how you can miss standard UX signals when you are not expecting them.

Updated Reprint - Migrating a TFS TFVC team project to a Git team project

This is a copy of the guest post done on the Microsoft UK web site published on the 7th June 2016

This is a revised version of a post originally published in August 2014. In this revision I have updated version numbers and links for tools used and added a discussion of adapting the process to support VSTS.

The code for this post can be found in my GitHub Repo


In the past I've written on the theory behind migrating TFVC to Git with history. I've since used this process for real, as opposed to as a proof of concept, and this post documents my experiences. The requirement was to move an on-premises TFS 2013.2 Scrum Team Project using TFVC to another on premises TFS 2013.2 Scrum Team Project, but this time using Git.

This process is equally applicable to any version of TFS that supports Git, and to VSTS.

Create new team project

On the target server create a new team project using the same (or as close as possible) process template as was used on the source TFS server. As we were using the same non-customised process template for both the source and the target we did not have to worry over any work item customisation. However, if you were changing the process template, this is where you would do any customisation required.

Remember that if you are targeting VSTS your customisation options are limited. You canadd custom fields to VSTS as of the time of writing (May 2016), but that is all.

Adding a field to all Work Item Types

We need to be able to associate the old work item ID with the new migrated one. For on-premises TFS servers, the TFS Integration Platform has a feature to do this automatically, but it suffers a bug. It is meant to automatically add a field for this purpose, but it actually needs it to be manually added prior to the migration.

To do this edit we need to either:

  1. Edit the process templates in place using the Process Template Editor Power Tool
  2. Export the WIT with WITADMIN.exe and edit them in Notepad and re-import them

In either case the field to add to ALL WORK ITEM TYPES is as follows:

<FIELD refname="TfsMigrationTool.ReflectedWorkItemId" name="ReflectedWorkItemId" type="String">

Once the edit is made the revised work item types need to be re-imported back into the new Team project.

If you are using VSTS this way of adding the field is not an option, but we can add custom fields to a work item type to VSTS. If we do this you will need to use the TFS Integration Mapper tool (mentioned below) to make sure the required old work item ID ends up in your custom location. TFS Integration Platform will not do this by default, butI have documented this process in an associated post.

The Work Item Migration

The actual work item migration is done using the TFS Integration Platform. This tool says it only supports TFS 2012, but it will function with newer versions of TFS as well as VSTS. This will move over all work item types from the source team project to the target team project. The process is as follows:

  1. Install TFS Integration Platform.
  2. Load TFS Integration Platform, as it seems it must be loaded after the team project is created, else it gets confused!
  3. Select 'Create New'.
  4. Pick the 'Team Foundation Server\WorkItemTracking' template. As we are migrating with the same process template this is OK. If you need to change field mappings use the template for field matching and look at the TFS Integration Mapper tool.
  5. Provide a sensible name for the migration. Not really needed for a one-off migration, but if testing, it's easy to end up with many test runs all of the same name, which is confusing in the logs.
  6. Pick the source server and team project as the left server.
  7. Pick the target server and team project as the right server.
  8. Accept the defaults and save to database.
  9. On the left menu select Start. The UI on this tool is not great. Avoid looking on the output tab as this seems to slow the process. Also, altering the refresh time on the options for once a minute seems to help process performance. All details of actions are placed in log files so nothing is lost by these changes.
  10. The migration should complete without any issues, assuming there are no outstanding template issues that need to be resolved.

Article image

Add the New ID to the Changesets on the source server

The key to this migration process to retain the links between the work items and source code checkins. This is done using the technique I outlined in the previous post i.e. editing the comments field of the changeset on the source team project prior to migration the source, adding #123 style references to point to the new work items on the target server.

To do this I used some PowerShell. This PowerShell was written before the new TFS REST API was available, hence uses the older C# API. If I was writing it now I would have used the REST API.

function Update-TfsCommentWithMigratedId
{

<# 
.SYNOPSIS 
This function is used as part of the migration for TFVC to Git to help retain checkin associations to work items 
 
.DESCRIPTION 
This function takes two team project references and looks up changset association in the source team project, it then looks for  
the revised work itme IT in the new team project and updates the source changeset 
 
.PARAMETER SourceCollectionUri 
Source TFS Collection URI 
 
.PARAMETER TargetCollectionUri 
Target TFS Collection URI 
 
.PARAMETER SourceTeamProject 
Source Team Project Name 
 
.EXAMPLE 
 
Update-TfsCommentWithMigratedId -SourceCollectionUri "http://server1:8080/tfs/defaultcollection" -TargetCollectionUri "http://server2:8080/tfs/defaultcollection" -SourceTeamProject "Scrumproject" 
 
#> 
 
    Param 
    ( 
    [Parameter(Mandatory=$true)] 
    [uri] $SourceCollectionUri,  
 
    [Parameter(Mandatory=$true)] 
    [uri] $TargetCollectionUri, 
 
    [Parameter(Mandatory=$true)] 
    [string] $SourceTeamProject 
 
    ) 
 
    # get the source TPC 
    $sourceTeamProjectCollection = New-Object Microsoft.TeamFoundation.Client.TfsTeamProjectCollection($sourceCollectionUri) 
    # get the TFVC repository 
    $vcService = $sourceTeamProjectCollection.GetService([Microsoft.TeamFoundation.VersionControl.Client.VersionControlServer]) 
    # get the target TPC 
    $targetTeamProjectCollection = New-Object Microsoft.TeamFoundation.Client.TfsTeamProjectCollection($targetCollectionUri) 
    #Get the work item store 
    $wiService = $targetTeamProjectCollection.GetService([Microsoft.TeamFoundation.WorkItemTracking.Client.WorkItemStore]) 
 
    # Find all the changesets for the selected team project on the source server 
    foreach ($cs in $vcService.QueryHistory(”$/$SourceTeamProject”, [Microsoft.TeamFoundation.VersionControl.Client.RecursionType]::Full, [Int32]::MaxValue)) 
    { 
        if ($cs.WorkItems.Count -gt 0) 
        { 
            foreach ($wi in $cs.WorkItems) 
            { 
                "Changeset {0} linked to workitem {1}" -f $cs.ChangesetId, $wi.Id 
                # find new id for each changeset on the target server 
                foreach ($newwi in $wiService.Query("select id  FROM WorkItems WHERE [TfsMigrationTool.ReflectedWorkItemId] = '" + $wi.id + "'")) 
                { 
                    # if ID found update the source server if the tag has not already been added 
                    # we have to esc the [ as gets treated as a regular expression 
                    # we need the white space around between the [] else the TFS agent does not find the tags  
                    if ($cs.Comment -match "\[ Migrated ID #{0} \]" -f $newwi.Id) 
                    { 
                        Write-Output ("New Id {0} already associated with changeset {1}" -f $newwi.Id , $cs.ChangesetId) 
                    } else { 
                        Write-Output ("New Id {0} being associated with changeset {1}" -f $newwi.Id, $cs.ChangesetId ) 
                        $cs.Comment += "[ Migrated ID #{0} ]" -f $newwi.Id 
                    } 
                } 
            } 
            $cs.Update() 
        } 
    } 
}
     

With the usage:

Update-TfsCommentWithMigratedId -SourceCollectionUri "http://localhost:8080/tfs/defaultcollection" -TargetCollectionUri "http://localhost:8080/tfs/defaultcollection" -SourceTeamProject "Old team project"  

NOTE: This script is written so that it can be run multiple times, but only adds the migration entries once for any given changeset. This means both it and TFS Integration Platform can be run repeatedly on the same migration to do a staged migration e.g. get the bulk of the content over first whilst the team is using the old team project, then do a smaller migration of the later changes when the actual swap over happens.

When this script is run expect to see output similar to:

Article image

You can see the impact of the script in Visual Studio Team Explorer or the TFS web client when looking at changesets in the old team project. Expect to see a changeset comment in the form shown below with new [ Migrated ID #123 ] blocks in the comment field, with 123 being the work item ID on the new team project. Also note the changeset is still associated with the old work item ID on the source server.

Article image

NOTE: The space after the #123 is vital. If it is not there, then the TFS job agent cannot find the tag to associate the commit to a work item after the migration.

Source code migration

The source code can now be migrated. This is done by cloning the TFVC code to a local Git repo and then pushing it up to the new TFS Git repo using Git TF. We clone the source to a local repo in the folder localrepo with the -deep option used to retain history.

git tf clone http://typhoontfs:8080/tfs/defaultcollection '$/Scrum TFVC Source/Main' localrepo --deep

NOTE: I have seen problems with this command. On larger code bases we saw the error 'TF 400732 server cancelled error' as files were said to be missing or we had no permission - neither of which was true. This problem was repeated on a number of machines, including one that had in the past managed to do the clone. It was thought the issue was on the server connectivity, but no errors were logged.

As a work around the Git-TFS tool was used. This community tool uses the .NET TFS API, unlike the Microsoft one which uses the Java TFS API. Unfortunately, it also gave TF400732 errors, but did provide a suggested command line to retry continue, which continued from where it errored.

The command to do the clone was:

Git tfs clone http://typhoontfs:8080/tfs/defaultcollection '$/Scrum TFVC Source/Main' localrepo

The command to continue after an error was (from within the repo folder):

Git tfs fetch  

It should be noted that Git-TFS seems a good deal faster than Git TF, presumably due to being a native .NET client as opposed to using the Java VM. Also, Git-TFS has support for converting TFVC branches to Git branches, something Git TF is not able to do. So for some people, Git-TFS will be a better tool to use.

Once the clone is complete, we need to add the TFS Git repo as a remote target and then push the changes up to the new team project. The exact commands for this stage are shown on the target TFS server. Load the web client, go to the code section and you should see the commands needed:

git remote add origin http://typhoontfs:8080/tfs/DefaultCollection/_git/newproject 
git push -u origin --all  

Once this stage is complete the new TFS Git repo can be used. The Git commits should have the correct historic date and work item associations as shown below. Note now that the migration ID comments match the work item associations.

Article image

NOTE: There may be a lack in the associations being shown immediately after the git push. This is because the associations are done by a background TFS job process which may take a while to catch up when there are a lot of commits. On one system I worked on this took days, not hours! Be patient.

Shared Test Steps

At this point all work items have been moved over and their various associations with source commits are retained e.g. PBIs link to test cases and tasks. However, there is a problem that any test cases that have shared steps will be pointing to the old shared step work items. As there is already an open source tool to do this update, there was no immediate need to rewrite it as a PowerShell tool. So to use the open source tool use the command line: 

UpdateSharedStep.exe http://localhost:8080/tfs/defaultcollection myproject

Test Plans and Suites

Historically in TFS, test plans and suites were not work items, they became work items in TFS 2013.3. This means if you need these moved over too, then you had to use the TFS API.

Though these scripts were written for TFS 2013.2, there is no reason for these same API calls not to work with newer versions of TFS or VSTS. Just remember to make sure you exclude the Test Plans and Suites work items from the migration performed TFS Integration Platform so you don't move them twice.

This script moves the three test suite types as follows:

  1. Static - Creates a new suite, finds the migrated IDs of the test cases on the source suite and adds them to the new suite.
  2. Dynamic - Creates a new suite using the existing work item query. IMPORTANT - The query is NOT edited, so it may or may not work depending on what it actually contained. These suites will need to be checked by a tester manually in all cases and their queries 'tweaked'.
  3. Requirements - Create a new suite based on the migrated IDs of the requirement work items. This is the only test suite type where we edit the name to make it consistent with the new requirement ID not the old.

The script is as follows: 

function Update-TestPlanAfterMigration
{
<# 
.SYNOPSIS 
This function migrates a test plan and all its child test suites to a different team project 
 
.DESCRIPTION 
This function migrates a test plan and all its child test suites to a different team project, reassign work item IDs as required 
 
.PARAMETER SourceCollectionUri 
Source TFS Collection URI 
 
.PARAMETER SourceTeamProject 
Source Team Project Name 
 
.PARAMETER SourceCollectionUri 
Target TFS Collection URI 
 
.PARAMETER SourceTeamProject 
Targe Team Project Name 
 
 
.EXAMPLE 
 
Update-TestPlanAfterMigration -SourceCollectionUri "http://server1:8080/tfs/defaultcollection" -TargetCollectionUri "http://serrver2:8080/tfs/defaultcollection"  -SourceTeamProjectName "Old project" -TargetTeamProjectName "New project" 
 
#> 
    param( 
    [Parameter(Mandatory=$true)] 
    [uri] $SourceCollectionUri, 
 
    [Parameter(Mandatory=$true)] 
    [string] $SourceTeamProjectName, 
 
    [Parameter(Mandatory=$true)] 
    [uri] $TargetCollectionUri, 
 
    [Parameter(Mandatory=$true)] 
    [string] $TargetTeamProjectName 
 
    ) 
 
    # Get TFS connections 
    $sourcetfs = [Microsoft.TeamFoundation.Client.TfsTeamProjectCollectionFactory]::GetTeamProjectCollection($SourceCollectionUri) 
    try 
    { 
        $Sourcetfs.EnsureAuthenticated() 
    } 
    catch 
    { 
        Write-Error "Error occurred trying to connect to project collection: $_ " 
        exit 1 
    } 
    $targettfs = [Microsoft.TeamFoundation.Client.TfsTeamProjectCollectionFactory]::GetTeamProjectCollection($TargetCollectionUri) 
    try 
    { 
        $Targettfs.EnsureAuthenticated() 
    } 
    catch 
    { 
        Write-Error "Error occurred trying to connect to project collection: $_ " 
        exit 1 
    } 
 
    # get the actual services 
    $sourcetestService = $sourcetfs.GetService("Microsoft.TeamFoundation.TestManagement.Client.ITestManagementService") 
    $targettestService = $targettfs.GetService("Microsoft.TeamFoundation.TestManagement.Client.ITestManagementService") 
    $sourceteamproject = $sourcetestService.GetTeamProject($sourceteamprojectname) 
    $targetteamproject = $targettestService.GetTeamProject($targetteamprojectname) 
    # Get the work item store 
    $wiService = $targettfs.GetService([Microsoft.TeamFoundation.WorkItemTracking.Client.WorkItemStore]) 
 
 
    # find all the plans in the source 
     foreach ($plan in $sourceteamproject.TestPlans.Query("Select * From TestPlan")) 
     { 
         if ($plan.RootSuite -ne $null -and $plan.RootSuite.Entries.Count -gt 0) 
         { 
            # copy the plan to the new tp 
            Write-Host("Migrating Test Plan - {0}" -f $plan.Name)  
            $newplan = $targetteamproject.TestPlans.Create(); 
            $newplan.Name = $plan.Name 
            $newplan.AreaPath = $plan.AreaPath 
            $newplan.Description = $plan.Description 
            $newplan.EndDate = $plan.EndDate 
            $newplan.StartDate = $plan.StartDate 
            $newplan.State = $plan.State 
            $newplan.Save(); 
            # we use a function as it can be recursive 
            MoveTestSuite -sourceSuite $plan.RootSuite -targetSuite $newplan.RootSuite -targetProject $targetteamproject -targetPlan $newplan -wiService $wiService 
            # and have to save the test plan again to persit the suites 
            $newplan.Save(); 
 
         } 
     } 
 
 
 

 
# - is missing in name so this method is not exposed when module loaded 
function MoveTestSuite 

<# 
.SYNOPSIS 
This function migrates a test suite and all its child test suites to a different team project 
 
.DESCRIPTION 
This function migrates a test suite and all its child test suites to a different team project, it is a helper function Move-TestPlan and will probably not be called directly from the command line 
 
.PARAMETER SourceSuite 
Source TFS test suite 
 
.PARAMETER TargetSuite 
Target TFS test suite 
 
.PARAMETER TargetPlan 
The new test plan the tests suite are being created in 
 
.PARAMETER targetProject 
The new team project test suite are being created in 
 
.PARAMETER WiService 
Work item service instance used for lookup 
 
 
.EXAMPLE 
 
Move-TestSuite -sourceSuite $plan.RootSuite -targetSuite $newplan.RootSuite -targetProject $targetteamproject -targetPlan $newplan -wiService $wiService 
 
#> 
    param  
    ( 
        [Parameter(Mandatory=$true)] 
        $sourceSuite, 
 
        [Parameter(Mandatory=$true)] 
        $targetSuite, 
 
        [Parameter(Mandatory=$true)] 
        $targetProject, 
 
        [Parameter(Mandatory=$true)] 
        $targetplan, 
 
        [Parameter(Mandatory=$true)] 
        $wiService 
    ) 
 
    foreach ($suite_entry in $sourceSuite.Entries) 
    { 
       # get the suite to a local variable to make it easier to pass around 
       $suite = $suite_entry.TestSuite 
       if ($suite -ne $null) 
       { 
           # we have to build a suite of the correct type 
           if ($suite.IsStaticTestSuite -eq $true) 
           { 
                Write-Host("    Migrating static test suite - {0}" -f $suite.Title)       
                $newsuite = $targetProject.TestSuites.CreateStatic() 
                $newsuite.Title = $suite.Title 
                $newsuite.Description = $suite.Description  
                $newsuite.State = $suite.State  
                # need to add the suite to the plan else you cannot add test cases 
                $targetSuite.Entries.Add($newSuite) >$nul # sent to null as we get output 
                foreach ($test in $suite.TestCases) 
                { 
                    $migratedTestCaseIds = $targetProject.TestCases.Query("Select * from [WorkItems] where [TfsMigrationTool.ReflectedWorkItemId] = '{0}'" -f $Test.Id) 
                    # we assume we only get one match 
                    if ($migratedTestCaseIds[0] -ne $null) 
                    { 
                        Write-Host ("        Test {0} has been migrated to {1} and added to suite {2}" -f $Test.Id , $migratedTestCaseIds[0].Id, $newsuite.Title) 
                        $newsuite.Entries.Add($targetProject.TestCases.Find($migratedTestCaseIds[0].Id))  >$nul # sent to null as we get output 
                    } 
                } 
           } 
 
    
           if ($suite.IsDynamicTestSuite -eq $true) 
           { 
               Write-Host("    Migrating query based test suite - {0} (Note - query may need editing)" -f $suite.Title)       
               $newsuite = $targetProject.TestSuites.CreateDynamic() 
               $newsuite.Title = $suite.Title 
               $newsuite.Description = $suite.Description  
               $newsuite.State = $suite.State  
               $newsuite.Query = $suite.Query 
 
               $targetSuite.Entries.Add($newSuite) >$nul # sent to null as we get output 
               # we don't need to add tests as this is done dynamically 
   
           } 
 
           if ($suite.IsRequirementTestSuite -eq $true) 
           { 
               $newwis = $wiService.Query("select *  FROM WorkItems WHERE [TfsMigrationTool.ReflectedWorkItemId] = '{0}'" -f $suite.RequirementId)   
               if ($newwis[0] -ne $null) 
               { 
                    Write-Host("    Migrating requirement based test suite - {0} to new requirement ID {1}" -f $suite.Title, $newwis[0].Id )     
        
                    $newsuite = $targetProject.TestSuites.CreateRequirement($newwis[0]) 
                    $newsuite.Title = $suite.Title -replace $suite.RequirementId, $newwis[0].Id 
                    $newsuite.Description = $suite.Description  
                    $newsuite.State = $suite.State  
                    $targetSuite.Entries.Add($newSuite) >$nul # sent to null as we get output 
                    # we don't need to add tests as this is done dynamically 
               } 
           } 
   
           # look for child test cases 
           if ($suite.Entries.Count -gt 0) 
           { 
                 MoveTestSuite -sourceSuite $suite -targetSuite $newsuite -targetProject $targetteamproject -targetPlan $newplan -wiService $wiService 
           } 
        } 
    } 
}
     

NOTE: This script needs PowerShell 3.0 installed. This appears to be because some the TFS assemblies are .NET 4.5 which is not supported by previous PowerShell versions. If the version is wrong the test suite migration will fail as the TestPlan (ITestPlanHelper) object will be null.

The command to run the migration of test plans is:

Update-TestPlanAfterMigration -SourceCollectionUri "http://typhoontfs:8080/tfs/defaultcollection" -TargetCollectionUri "http://typhoontfs:8080/tfs/defaultcollection" -SourceTeamProjectName "Scrum TFVC Source" -TargetTeamProjectName "NewProject"  

This will create the new set of test plans and suites in addition to any already in place on the target server. It should give an output similar to:

Article image

Summary

Once all this is done you should have migrated a TFVC team project to a new team project based on Git on either on-premises TFS or VSTS, retaining as much history as is possible. I hope you find this of use!

This article was first published on the Microsoft’s UK Developers site Migrating a TFS TFVC based team project to a Git team project - a practical example originally published August the 15th 2014 updated 7 June 2016