I spent some time with the TFS Migration and Synchronization Toolkit this week and I thought that I'd share my experiences with it to help out anyone else who wants to evaluate this toolkit. I found the included documentation to be a little weak and in some areas if found that parts were missing, so maybe this post can fill the documentation out a bit.
I had a pretty simple goal in mind when I started looking at the toolkit. I just wanted to run a simple demo where I synchronize a SharePoint task list with work items in a Team System project. The toolkit includes the required pieces to make this happen, but the additional undocumented steps I had to perform were a little frustrating (and time consuming as I had to hunt down solutions to my issues). So here are the steps I took to get this simple demo working.
I was working on the newly released Team Suite Trial VPC from Microsoft, so I was working with both Visual Studio 2008 and Team Foundation Server 2008.
I started by logging into the VPC as Darren (an account with local administrative privileges).
Once logged in, I decided that I was going to work with an existing team project (eBanking1). If you want, you can work with a new team project, but of course, you'll need to create it first.
The code included in the toolkit sample uses a custom work item, so the next step I needed to perform was to import the work item (since the toolkit team was so nice to include the work item definition xml file (WssTask.xml located in WIT\Wss2TfsWit\). I initially experienced some issues importing this work item (this may be a 2005 vs. 2008 issue), but a few adjustments to the .xml file and I was golden.
First, replace line 2 with the following:
<WITD xmlns:witd="http://schemas.microsoft.com/VisualStudio/2005/workitemtracking/typedef" application="Work item type editor" version="1.0">
and replace line 210 with:
</WITD>
Next, add the following field definition somewhere in the field definition area (I started at line 43):
<FIELD name="History" refname="System.History" type="History">
<HELPTEXT>Discussion thread and other historical information</HELPTEXT>
</FIELD>
Once I made those edits, I used the Process Template Editor to import the work item into my target team project (you've all downloaded the TFS 2008 PowerTool, haven't you? If not, shame on you and go get it from here ASAP).
The next item that needed to be taken care of was the creation of the database used by the migration tool. The required SQL scripts are also included with the toolkit and can be located in 'Toolkit\Wit\SQL\'. I used the installed instance of SQL Express to host my database, but you can use any SQL Server database. Before I could run the scripts, I needed to manually create the database (called MigrationToolkitTest) and once it was created, I just ran the two included scripts (first the script to create the table definitions and then the script to create the stored procedures).
Next, I logged into the team project's portal and ensured that the current user permissions allowed full control over the SharePoint site (see here for details).
Once the user had the appropriate SharePoint permissions, I added the currently logged in user to the TFS Server Account group using the TFSSecurity utility (syntax = tfssecurity.exe /server:http://yourserver:8080 /g+ srv: domain\account).
Now that all of the appropriate permissions were assigned, I needed to get the included code built. First, I opened the solution located in the Toolkit directory. If you're running Visual Studio 2008, you will be prompted to convert the solution, which was quite painless.
Once converted, I needed to make a few adjustments to get the solution to actually build. I'm going to assume that the C# compiler has been changed between 2005 and 2008 and that the build errors I was getting don't show up in 2005. The changes that I had to make involved changing the scope of a couple of property get statements. In both statements, the property was scoped as protected and I changed them both to be public. Both lines are found in the file named ChangeGrouping.cs (one on line 126 and one on line 286).
Once those changes were made, I was able to build the solution, but there were a few other changes that I needed to make to address a known issue.
- Move FireEvent(SessionStart, MigrationToolkitResources.SessionStarting call) right after initializing m_syncProcess member in Synchronize, SynchronizeFull and ProcessDeferredLinks method located in WorkItemTrackingSession.cs
- Move FireEvent(SessionAborted,...) in AbortImpl method right under m_syncProcess.Abort() call located in WorkItemTrackingSession.cs
Once those changes were accomplished, I was able to build the solution and produce all of the executables and dlls required. If you're planning on running the solution via the command line executable, you will need to copy all of the dll output from two projects (TfsLinking and Wss2TfsWIT) to the same directory as the console application. If you want to debug the solution from inside Visual Studio, you can make sure that the console application project references the two previously mentioned projects so that the output gets automatically copied to the output directory of the console application. One additional step you'll need to perform to allow debugging is add a call to the SampleConfig.xml to the Command Line are in the Debug property.
Speaking of the SampleConfig.xml file, the included documentation mentions a few areas where you'll need to make edits, but I'll expand on those instructions a bit.
First, since I only wanted to synchronize the task list and not worry about version control or linking, I removed both the <VC> sections and the <Linking> section (careful to leave the closing </Sessions> tag at the end of the <Linking> section).
I then edited the WIT section to use my test project (eBanking1) and changed the <BaseURL> to point at the team project's portal (eg:http://tfsrtm08/Sites/eBanking1).
I adjusted the Server section to point to my actual server (replacing where id=SampleTFS)
I adjusted the SQL section to use SQL Express by change the connection string to use '.\sqlexpress' and made the same edit to the <Server> property.
Once those changes were made to the SampleConfig file, I was able to run the command line application without error. To test the toolkit, I opened the team project portal's task list in Internet Explorer, added a couple of tasks and then ran the console application. Once completed, I used the team explorer to query for WSSTask work items and discovered my newly added SharePoint tasks had been copied over to WSSTask work items. I could then go and make changes to the tasks in SharePoint, rerun the console application and the changes would be reflected in Team System. Pretty cool.
I'm still dealing with a couple of problems. It looks like I'm having issues with the time set in SharePoint and the time synchronized in the corresponding work item in Team System and I get errors after creating more then 2 tasks, but I'm sure that these issues are just me being unfamiliar with setting up the toolkit. Hopefully I have these issues addressed with a little more digging.
Have you had any experiences with this toolkit that you'd like to share? Any successes or issues that you've encountered? Leave me a comment to spread the word (both good and bad).
Ta.
Steve Porter