As part of the VSTS Rangers initiative we created a “Getting Started” guide for the TFS Migration Tools. The document serves as a entry point to the solution, giving the user a walkthrough of the main artefacts of the platform, and will also be re-used as the hands-on-lab (HOL) manual at TechReady9.

The document contains a number of “NOTES” and has also raised a number of questions, all of which I will elaborate on in this post.

Clipart Illustration of a White Character Examining With A Magnifying Glass Questions that were raised by reviewers

  1. Why does the walk through cover the MigrationConsole and not the Service?
    • Initially the guide was created for VSTS Rangers working on the solution, to guide them through the process of setting up a quick testing environment.
    • When we started looking at re-using the guide for the hands-on-lab (HOL) at TechReady9 we decided to leave the guide unchanged, as the migration console is a great test application and more importantly, for the HOL, does not require administration and interaction with a windows service.
    • The primary objective was to avoid complexity in the walkthrough … however, in real-life, i.e. production environments, you should seriously consider using the service instead. The use and configuration of the service is documented in the Architecture Overview document.
  2. Why is the walk-through focused on the command line environment … where is the user interface?
    • The command line tools are very hard to use right now and therefore the decision to use them deserves an explanation.
    • The team has been focusing (razor sharp) on performance, scalability, correctness, robustness and reliability of the product under the bonnet and the TFS Version Control and Work Item Adapters. They could have decided to close the bonnet and create a pretty a face for the tools, but personally I support their decision to complete the engine first.
    • The next phase of the project is now focusing on creating the pretty and user-friendly interface, based on a sound engine, which includes installation, configuration, administration and monitoring. Even conflict resolution and administration will be less intimidating.
    • In parallel we will be revising the documentation to document the new user interfaces and to introduce them as part of the “Getting Started” walk-through. We will probably keep the guided tour as-is, adding an additional chapter for the new user interfaces.

Clipart Illustration of a White Character Taking Notes Down On A Clipboard, A Supervisor, Manager, Or Someone Taking Inventory Notes (Alerts) contained in the document

  1. Currently the default root name is C:\TfsMigrtData …
    • This is the default root name and can be changed by editing file MigrationToolServers.config file and changing the workspace root path.
    • Caution is advised and you should be careful to keep the name and path to an absolute minimum, so as to avoid the complete path length of the workspace root and working files exceeding the magic 259 characters.
  2. We are using $\TP-B\Fix as the target version control root to avoid a “VC content conflict type” conflict …
    • The current TFS Version Control Adapter reports the “VC content conflict type” if your target is empty. To keep conflict administration and resolution out of the getting started walkthrough, we opted for the workaround of moving from source $/TP-A to $/TP-B/Fix.
    • This is a known issue and has been reported for resolution in the final release.
  3. Once you run a migration session, the configuration is moved from the configuration file to the Migration database …
    • Once the configuration file has been read and processed, it is moved to the Migration database and used for subsequent migration runs … even if you specify an updated configuration file when running, for example, the MigrationConsole host.
    • This has led to a few trips of confusion and frustration for users of the solution and we have therefore reported it for resolution in the final release.
    • In the interim you could roll up your sleeves, explore the database and make the changes there … but don’t! We prefer to keep the database out of the user’s  world and you should therefore preferably change the Unique Id at the beginning of the configuration file to create a new session configuration.
      Configuration UniqueId="{13A76010-81C8-4AFD-A0B6-8FCBE46E757C}" FriendlyName="TR9 HOL".
    • If you are using Hyper-V, it is recommended that you use snapshots to create bookmarks in time and introduce the magical time machine and ability to roll-back in time. For example, before you install and after you have installed are two great snapshot opportunities. The former allows you to start by install a new version and the latter allows you to revert back to base if your configuration needed a few tweaks.
  4. Run the SetupSecurity.cmd …
    • tfssecurity /g+ srv: tfs2010b1x32t\Administrator /server:tfs2010b1x32t\defaultcollection
    • We are doing this as a work around to keep conflicts and the resolution thereof out of the basic walkthrough. We created a configuration file that defines the "BypassRule" enabled, which is a property set in the WIT update document, and enforces that all the WITD rule evaluations, such as valid value list, state transition, are disabled for the submitted data. The “bypassing of rules” requires that the account that submits the change must be in the Team Foundation Service Account … see Administrator Permissions are not enough for WIT migration by Curtis Pettit for a great explanation.
    • Alternatively we could create a configuration that has the field value mapping information in it, such that the conflict can be avoided.

Other Errors you may encounter

  1. Error: The open operation did not complete within the allotted timeout of 00:00:00.
    • The error, listed in detail below, can be caused if you re-install the solution on a system that already has a MigrationDB present, leaving the the connection string in the global configuration file pointing at an invalid database.
    • This is a known issue and has been reported for resolution in the final release.
       1: C:\SC\WSS2TFS\ReleaseCode\Tools\MigrationConsole\obj\x86\Debug>MigrationConsole.exe SampleConfig.xml
       2: [6/28/2009 7:42:25 PM] MigrationConsole started...
       3: [6/28/2009 7:42:27 PM] Error: The open operation did not complete within the allotted timeout of 00:00:00. The time allotted to this  operation may have been a portion of a longer timeout.
       4: [6/28/2009 7:42:36 PM] Loading the configuration file SampleConfig.xml failed
       5: [6/28/2009 7:42:36 PM] System.ArgumentException: The specified named connection is either not found in the configuration, not intend ed to be used with the EntityClient provider, or not valid.
       6:    at System.Data.EntityClient.EntityConnection.ChangeConnectionString(String newConnectionString)
       7:    at System.Data.EntityClient.EntityConnection..ctor(String connectionString)
       8:    at System.Data.Objects.ObjectContext.CreateEntityConnection(String connectionString)
       9:    at System.Data.Objects.ObjectContext..ctor(String connectionString, String defaultContainerName)
      10:    at Microsoft.TeamFoundation.Migration.EntityModel.TfsMigrationConsolidatedDBEntities..ctor()
      11:    at Microsoft.TeamFoundation.Migration.EntityModel.TfsMigrationConsolidatedDBEntities.CreateInstance()
      12:    at Microsoft.TeamFoundation.Migration.BusinessModel.BusinessModelManager.get_Context()
      13:    at Microsoft.TeamFoundation.Migration.BusinessModel.BusinessModelManager.IsConfigurationPersisted(Configuration config)
      14:    at Microsoft.TeamFoundation.Migration.BusinessModel.Configuration.TrySave()
      15:    at MigrationConsole.MigrationApp.LaunchFromConfigFile() in C:\SC\WSS2TFS\ReleaseCode\Tools\MigrationConsole\MigrationApp.cs:line 127
      16: Closing migraiton and runtime service host...
      17: [6/28/2009 7:42:48 PM] MigrationConsole completed...
      18: Press any key ...

What’s planned for the document?

Lime Green Man Using A Watering Can To Water New Grass Growing On Planet Earth, Symbolizing Someone Caring For The Environment Clipart Illustration

We will be removing the comments and introducing product fixes or additional walk-through sections, for example, working with and resolving conflicts. In addition, we will introduce the new administrative user interface, which vastly improves the life of the administration and end-user.

We are not sure how much of the changes will make it into the TechReady9 (TR9) edition, but for the edition that ships with the final product, we should be able to eradicate most notes and associated work arounds.