Migrating Team Foundation Server

Recently, I needed to migrate TFS from one server to another. I figured there would be a few challenges, but I was wrong. There were a lot of challenges. Adding to my frustration was my inability to find an online "How To" tutorial. There were a number of resources, but many of them didn't apply to me, or their "tips" weren't able to overcome the obstacles encountered. After some trial and error, I finally worked it out. Unfortunately, I didn't take good notes as I went along. But I'll try to recount it here as best as I can. Maybe my loss (time, sanity, etc.) can be your gain.

Here's the TFS version I was using, and a look at where I was coming from and where I was going to:

TFS Installation

I installed TFS on the target server. When the installation prompted me for the SQL Server instance, I chose my local SQL 2014 instance. The TFS installation rejected it, though. It said something like "TFS Express is only valid with SQL Server Express". [Grumble.] Instead of fighting, I decided to let the TFS installation install a new instance of SQL 2012 Express (more on this later). Moving along...I *think* I chose the "Standard Single Server" TFS configuration (I use TFS for version control only--I don't create builds or do anything SharePoint-related). I accepted most of the defaults and the install completed gracefully. Afterwards, I had the "DefaultCollection". I can't remember if that was created at install time, or if I created it manually with the TFS Admin Console. Again, I took few notes. Sorry for the lack of details. Looking at the new SQL 2012 Express instance, there were two new databases: [Tfs_Configuration] and [Tfs_DefaultCollection].

Specify A New SQL Instance

If you are migrating, but want to keep the databases on SQL 2012 Express, then you can skip this part. I wanted them moved to my SQL 2014 instance. So I did a traditional backup/restore from SQL 2012 Express to SQL 2014. I took new backups of the SQL 2014 databases, and then uninstalled SQL 2012 Express. Then I had to configure TFS to connect to a different SQL instance. Within the web.config file (%ProgramFiles%\Microsoft Team Foundation Server 12.0\Application Tier\Web Services\web.config), I found an application setting named "applicationDatabase". I made a backup copy of web.config first, then I changed the "applicationDatabase" value. It should be in a recognizable format if you're familiar with SQL Server connection strings. You can also make this change within IIS. It was there that I noticed a few other settings that contained SQL connection strings. Check out the following in IIS and change settings as needed:

After changing the IIS settings, you may want to restart the IIS service and the Visual Studio Team Foundation Background Job Agent service. This may not strictly be necessary, but I assumed it was and restarted both services. (On a non-production system, there's really nothing to lose by restarting those services, right?)

To verify the changes above, open the TFS Admin Console. You should be able to click "Application Tier" without getting an error. Click "Team Project Collections" next. Again (hopefully), you won't get any errors, and you can verify the correct SQL connectivity information has been propagated to TFS.

Migration

On the old (source) server, open IIS. Navigate to "tfs" and click on Application Settings. Get the value of the "applicationId" setting--you'll need this for later on the new (target) server. If you don't have recent (or recent enough) database backups of [Tfs_Configuration] and [Tfs_DefaultCollection], create them now. After the backups are done, I suggest taking the two databases offline.

On the new (target) server, restore the backups of [Tfs_Configuration] and [Tfs_DefaultCollection] from the old (source) server. You'll be overwriting the existing databases. (You should have previously backed them up, as mentioned above.) After the restores are finished, open IIS. Navigate to "tfs", open Application Settings, and double-click the "applicationId" setting. Replace the value with the applicationId from the old (source) server.

As a result of overwriting the [Tfs_Configuration] database, the TFS Notification URL and/or Server URL may be wrong. Open TSF Admin Console, navigate to the Application Tier, and click Change URLs. Change either (or both) URLs, as needed. Be sure to test them, too. (An IIS reset may be necessary before or after this step.)

Now open Visual Studio and connect to TFS.

Disclaimers

As mentioned above, I didn't take notes as I worked through the migration. I went back to get the screen shots after the fact. I may have missed a step or two, or gotten something out of order. But hopefully, all the pieces to the puzzle are there. Good luck. And happy coding!