TN1502: Configuring Windows SharePoint Services 3.0 on a Remote Server to work with Visual Studio 2005 Team Foundation Server

Introduction

Visual Studio 2005 Team Foundation Server uses Windows SharePoint Services (WSS) 2.0 to enable team project portal functionality. Since the release of WSS 3.0, customers have wanted to know how to integrate it with Team Foundation Server. This document shows you how to configure Team Foundation Server 2005 to integrate with a remote WSS 3.0 server or server farm. However, if you want to configure WSS 3.0 on the application tier of your Team Foundation Server deployment, see TN1501: Configuring Windows SharePoint Services 3.0 on the Visual Studio 2005 Team Foundation Server Application Tier.

Team Foundation Server requires the installation of WSS 2.0 on the Team Foundation Server application tier for installation and serviceability. You need to keep WSS 2.0 installed and configured on the default Web site on the Team Foundation Server application tier.

Installation Checklist

The following checklist summarizes what you need in order to enable Team Foundation Server to work with WSS 3.0 on a remote server or server farm.

When you complete this procedure, install a hotfix on all the Team Explorer clients that will be creating new team projects. To get this hotfix, contact Microsoft Support and reference KB Article 932544. Since it takes time to process your request, get the hotfix before you make any changes.
Be sure your Team Foundation Server installation includes WSS 2.0 with Service Pack 2 and ASP.NET 2.0.
Be sure you install WSS 3.0 on a remote server or server farm within your organization. For more information on installing and configuring WSS 3.0, see Upgrading to Windows SharePoint Services 3.0.
If you have existing team project portal sites you want to migrate to the new WSS 3.0 server or server farm, be sure to follow the following migration documentation: Deploy a new farm, then migrate databases (Windows SharePoint Services).
Be sure the WSS 3.0 administration port is open on the Windows Firewall and any other firewall. This enables Team Explorer to access the site when it creates a new project through the Project Creation Wizard.
Change the Team Foundation Server registration entries to use the new SharePoint location (instead of the default Web site on the Team Foundation Server application tier).
Be sure that users who want to create new team project instances understand they must have STS Administrator privileges on the new WSS 3.0 instance.

Note: Do not uninstall WSS 2.0 from the Team Foundation Server application tier computer at any point. Doing this will prevent you from running a repair operation, installing service packs or hot fixes, upgrading the server, or installing and using an application-tier standby server.

Procedures

On the remote WSS 3.0 Server, ensure that the SharePoint administration port is open in the Windows Firewall.
1. On the remote WSS 3.0 server, click Start, point to All Programs, point to Administrative Tools, and then click SharePoint 3.0 Central Administration. The address of this site includes the admin port number. Record this port number.
2. If you are using the built-in Windows Firewall, follow these steps:
  1. To open the Windows Firewall control panel applet, click Start, point to Control Panel, and then click Windows Firewall.
  2. Click the Exceptions tab.
  3. If there is no exception for the SharePoint Administration port, add an exception by clicking Add Port, enter a name and the port number recorded in 1a, and then click OK.
  4. Click OK.
3. If you are using a different type of firewall, add an exception for the port number recorded in 1a.
Configure WSS 3.0 to use the Team Foundation Server site templates.
1. Obtain the WSS 3.0 MSF templates (MSFAgileWSS3.stp & MSFCMMIWSS3.stp).
2. Open a Command Prompt window on the WSS 3.0 server and execute the following commands. Be sure to modify [shareLocation] accordingly based on the location to where you copied the template files.
  cd "%ProgramFiles%\Common Files\Microsoft Shared\Web Server Extensions\12\Bin”
  Stsadm.exe -o addtemplate -filename "[shareLocation]\MSFAgileWSS3.stp" -title VSTS_MSFAgile
  Stsadm.exe -o addtemplate -filename "[shareLocation]\MSFCMMIWSS3.stp" -title VSTS_MSF_CMMI
  iisreset
Update the Team Foundation Server application-tier SharePoint Service Registration location entry to point to the location of the new WSS 3.0.
1. Modify the sample XML below, substituting the entries for [protocol], [RemoteWSSServerName], [port] and [adminPort] with those of the new WSS 3.0 server. Typically, protocol will refer to http or https. The [adminPort] value is the value you recorded in step 1a. Also, note that you can change the SharePoint default “sites” value depending on how you have configured the new Web application. (SharePoint managed URL paths).
  <RegistrationEntries> <RegistrationEntry> <Type>Wss</Type> <ChangeType>Change</ChangeType> <ServiceInterfaces> <ServiceInterface> <Name>WssAdminService</Name> <Url>[protocol]://[remoteWSSServerName]:[adminPort]/_vti_adm/admin.asmx</Url> </ServiceInterface> <ServiceInterface> <Name>BaseServerUrl</Name> <Url>[protocol]://[remoteWSSServerName]:[port]</Url> </ServiceInterface> <ServiceInterface> <Name>BaseSiteUrl</Name> <Url>[protocol]://[remoteWSSServerName]:[port]/sites</Url> </ServiceInterface> <ServiceInterface> <Name>BaseSiteUnc</Name> <Url>\\[remoteWSSServerName]\sites</Url> </ServiceInterface> </ServiceInterfaces> </RegistrationEntry> </RegistrationEntries>
2. Save your changes to the sample as STS_registration.xml. Be sure that the Team Foundation Server application tier computer can access the file.
3. Open a Command Prompt window on the Team Foundation Server application tier computer and execute the following commands (substituting your Team Foundation Server data tier computer name for [myDTserver] in the TFSReg.exe command here):
  iisreset /stop
  “%programfiles%\Microsoft Visual Studio 2005 Team Foundation Server\Tools”
  TFSReg.exe STS_registration.xml [myDTserver]
  iisreset /start
4. Confirm that your changes were successful. To do this, follow these steps:
  1. On the application tier computer, open Internet Explorer.
  2. Visit http://localhost:8080/services/v1.0/registration.asmx.
  3. Click GetRegistrationEntries.
  4. On the next page, click Invoke.
  5. Check that the service interface changes that you made through running TfsReg.exe are present in the resulting XML.
Fix the Reporting Web parts and lists on the Team Foundation Server portal sites.
By default, the Web part and links that display reports on the project portal will show a link, which points to a redirector page. However, this redirector page is installed on the Team Foundation Server application tier. Therefore, this page is not on the SharePoint server. The following steps enable you to fix this problem.
Note: The following procedure only works for one Team Foundation Server in your enterprise deployment. You should only use it for your primary (most heavily used) Team Foundation Server because the current reporting redirector page can only redirect to one SQL Report Server (installed on the application tier) based on a registry setting. This document has more instructions for other servers and portal sites.
1. Locate the tfsredirect.aspx page, and then copy it to the remote SharePoint server(s).
  1. On the application tier server, open the following directory:
    “%programfiles%\Common Files\Microsoft Shared\web server extensions\60\TEMPLATE\LAYOUTS”
  2. Copy the tfsredirect.aspx file located in this directory to a share visible to the WSS 3.0 server.
  3. On the WSS 3.0 server, copy the tfsredirect.aspx file to the following location:
    “%programfiles%\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\LAYOUTS”
2. On the WSS 3.0 server, open regedit and create the following registry key:
  WARNING: If you use Registry Editor incorrectly, you may be required to reinstall your operating system. Microsoft cannot guarantee that you can solve problems that result from using Registry Editor incorrectly. Use the Registry Editor at your own risk.
  HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\VisualStudio\8.0\TeamFoundation\ReportServer
3. Under the “ReportServer” key you created in the step above, create a new string value key named “Key”. The value of this key should be assigned to the URL of the Team Foundation Server application tier computer (for example, http://myAppTierServerName). For other Team Foundation Server instances supported by this WSS 3.0 server or server farm, the steps enable you to fix the portal site for each team project portal individually. This also means that for new team projects created on those Team Foundation Server application tier instances, you must follow this procedure each time. If you plan to support team projects from other Team Foundation Server application tier computers on this WSS 3.0 server, you must perform the following steps for each team project that exists on an alternate Team Foundation Server application tier computer.
  1. On the team project portal site, click Edit Shared Page, and then click Design this page.
  2. On the Remaining Work Web part click Edit, and then click Modify Shared Web Part.
  3. Under the Page Viewer in the right-hand pane, in the Link box, replace the URL with the following URL, substituting myATserver and MyTeamProjectName with the names of the corresponding Team Foundation Server application tier server and team project names:
    http://myATserver/ReportServer/Pages/ReportViewer.aspx?%2fMyTeamProjectName%2fRemaining+Work&rs:toolbar=false&rs:Command=Render
4. To change the Web links for reporting, you must use Microsoft Office SharePoint Designer 2007.
  1. Open Microsoft Office SharePoint Designer 2007.
  2. Click File, click Open Site, enter the newly-created team site (for example, http://remoteWSSServerName/sites/MyTeamProjectName), and then click OK.
  3. Click Site, and then click Navigation.
  4. Right-click on the Reports node, and click View Subtree Only.
  5. Right-click on the parent Report node and click Open.
  6. Change the URL listed in the Address field to the following, substituting myATserver and myTeamProjectName with the names of the corresponding Team Foundation Server application tier server and team project names:
    http://myATserver/Reports/Pages/Folder.aspx?ItemPath=%2fmyTeamProjectName&ViewMode=Detail
  7. For each of the child nodes of the Report, right-click, and click Open. Then change the URL listed in the Address field to reflect the appropriate Team Foundation Server application tier and team project names. The exact URL will vary for each child node depending on the type of report being retrieved, so make the appropriate fixes for each child node in this Reports tree. For example:
    http://myATserver/sites/myTeamProjectName/_layouts/tfsredirect.aspx?IsReport=1&ReportName=Bug+Rates&ShowToolbar=1
    becomes
    http://myATserver/ReportServer/Pages/ReportViewer.aspx?%2fmyTeamProjectName%2fBug+Rates&rs:toolbar=false&rs:Command=Render
  8. Once you have finished editing the URLs, close the site, and click Save Changes.
Client Considerations.
Now that you have configured your Team Foundation Server to use a new WSS 3.0 Web application, you must configure your client computers properly.
1. Check the Team Explorer cache. Team Explorer is the add-in within Visual Studio 2005 that provides integration with Team Foundation Server functionality. Team Explorer receives the WSS URL from Team Foundation Server. This value is cached with a default cache timeout of 7200 seconds (two hours). If you perform this update with enough downtime before clients begin to reconnect, you do not need to take further action. However, if clients need to connect to the team project portals before the cache time has expired, you may want to invalidate the cache manually. To do this, each client needs to close all open instances of Visual Studio 2005, and then delete the following folder: “%USERPROFILE%\Local Settings\Application Data\Microsoft\Team Foundation\1.0”. When clients open Visual Studio 2005 again, each client will retrieve the new team project portal URL.
2. Update bookmarks and other links. Typically, users access a team project portal via a bookmark or follow a link from another location such as a document or another Web page. You need to notify users of the new location for their team project portals. If you migrate old WSS 2.0 sites to WSS 3.0, you should edit the old WSS 2.0 sites to display a prominent message with a pointer to the new WSS 3.0 version of the site. This way, users who accidentally visit the old location will know they are accessing the retired site.
3. Install the Project Creation Wizard Hotfix. For clients who need to create new team projects within Team Foundation Server must install the hotfix previously described in the Checklist. After installing the hotfix, the client might have to to recycle the client-side cache as described in step 5a above.
4. Test the solution. Perform this step after performing step 5c. Be sure you have refreshed the cache described in 5a. On a computer that is running Team Explorer, verify that you can access the SharePoint site and that you have STS Administrator permissions for the SharePoint server. Open Team Explorer, connect to the Team Foundation Server, and try to create a new team project. The new team project portal site should be created on the WSS 3.0 Web application. While this will not test all of the functionality described in this document, this is a good indicator that you are on the right track toward an operable solution.

Support for this Solution

If you have trouble implementing this solution, you may contact Microsoft Support, or visit the Team Foundation Server – Setup Forum. In addition, support for Windows SharePoint Services 3.0 is built-in to Visual Studio Team System 2008 Team Foundation Server.

Microsoft Services can help you enable this functionality via a services agreement. For more information about this option, contact your local Microsoft account team.

Other Considerations

The Team Foundation Server backup and restoration guidelines assume data pertinent to all projects on the server are persisted on the Team Foundation Server data tier. However, by using a remote SharePoint server, some of the data associated with a team project are now persisted in a different location. This means administrators must make allowances as they back up and restore this distributed data.