Search Wiki:

SharePoint Enterprise Search Migration Tool for SharePoint Server 2010

When you upgrade from Microsoft Office SharePoint Server 2007 to Microsoft SharePoint Server 2010 by using the database attach approach, you upgrade only the content for your environment and not the configuration settings. This means that you must transfer settings that you want to preserve from the old farm to the new farm, including search related data such as best bets, search scopes, and site collection search settings. This is a challenging task if you need to do it manually.

The SharePoint Enterprise Search Migration tool for Microsoft SharePoint Server 2010 shows how to programmatically export and import search related data between Office SharePoint Server 2007, SharePoint Server 2010, and FAST Search Server 2010 for SharePoint when you upgrade by using the database attach approach, so you do not have to migrate this data manually.

The following table lists the migration paths that are supported by the tool:


Table 1. Supported migration paths
Starting Product Ending Product
Office SharePoint Server 2007 SharePoint Server 2010
Office SharePoint Server 2007 FAST Search Server 2010 for SharePoint
SharePoint Server 2010 SharePoint Server 2010
SharePoint Server 2010 FAST Search Server 2010 for SharePoint

The tool handles migration of the following search data:
  • Best bets
  • Search scopes
  • Site collection search center URL
  • Dropdown mode
  • Search results page URL

You can modify the sample code to extend the functionality to migrate additional search data.

Projects in the SearchMigrationTool Solution

The SearchMigrationTool solution contains the following projects:
  • Common
  • SearchMigration
  • O12Layer
  • O14Layer
  • FS14Layer

Common

The Common project contains all the shared code for the migration tool, and includes the following files:
Common.cs
The class model for the application, which applies to all versions of SharePoint that the tool can be used for.
Util.cs
Contains the static public utility routines.
XmlFileSample.xml
Sample input/output XML file, provided as a reference.
XmlInputFileSchema.xsd
Defines the XML schema for the input/output file.
XmlValidator.cs
Contains class to validate the input/output XML against the XML schema.

SearchMigration

The SearchMigration project contains the main executable for the SharePoint Enterprise Search Migration tool.

O12Layer

The O12Layer project contains an implementation of the Common project's abstract class MossLayer named
O12Layer. This implementation is dependent on Office SharePoint Server 2007, and runs all the code specific to this version.

O14Layer

The O14Layer project contains an implementation of the Common project's abstract class MossLayer named
O14Layer. This implementation is dependent on SharePoint Server 2010, and runs all the code specific to this version.

FS14Layer

The FS14Layer project contains an implementation of the Common project's abstract class MossLayer named FS14Layer. This implementation is dependent on SharePoint Server 2010 and FAST Search Server 2010 for SharePoint, and runs all the code specific to FAST Search Server 2010 for SharePoint.

Setup_x64

This is the setup project that builds the installer for the tool for 64-bit systems.

Setup_x86

This is the setup project that builds the installer for the tool for x86-bit systems.

Installing and Configuring the SearchMigrationTool Solution

The MSDN Code Gallery resource for the SharePoint Enterprise Search Migration Tool contains the source code for the tool.
To install SharePoint Enterprise Search Migration tool source
  1. Download Source.zip from the Downloads tab of the resource page.
  2. Extract the contents to a folder on your computer.
  3. Open the SearchMigrationTool solution in Microsoft Visual Studio.

Reference Assemblies

The solution contains projects that reference assemblies from Office SharePoint Server 2007 and SharePoint Server 2010. To compile the solution, you need to ensure that both versions of the assemblies are available. If you are compiling the solution on a computer that does not have either one or both versions installed, you need to copy these files to a local folder. The references are set up to look for the following assembly files in the specified locations:
Office SharePoint Server 2007
  • \SearchMigration\MossAssemblies\12\Microsoft.Office.Server.dll
  • \SearchMigration\MossAssemblies\12\Microsoft.Office.Server.Search.dll
  • \SearchMigration\MossAssemblies\12\Microsoft.SharePoint.dll

SharePoint Server 2010
  • \SearchMigration\MossAssemblies\14\Ship\Microsoft.Office.Server.dll
  • \SearchMigration\MossAssemblies\14\Ship\Microsoft.Office.Server.Search.dll
  • \SearchMigration\MossAssemblies\14\Ship\Microsoft.SharePoint.dll
  • \SearchMigration\MossAssemblies\14\Ship\Microsoft.SharePoint.Extended.Administration.Common.dll
  • \SearchMigration\MossAssemblies\14\Ship\Microsoft.SharePoint.Extended.Administration.dll

Common Project Pre-Build Event

The Common project contains a custom pre-build event that uses the XML Schema Definition Tool (Xsd.exe) to generate classes based on the XmlInputFileSchema.xsd file. The pre-build event specifies the following location for the Xsd.exe tool:
%ProgramFiles(x86)%\Microsoft SDKs\Windows\v6.0A\bin\xsd.exe

If the Xsd.exe tool location is different on your computer, you need to change the path specified in the pre-build event.
To change the path specified for the Xsd.exe tool

1. Right-click the Common project in Solution Explorer and select Properties.

2. On the Build Events tab of the Properties dialog, click Edit Pre-Build….

3. In the Pre-build Event Command Line textbox, update the path specified for the line containing the following SET command so that it matches the location of the Xsd.exe tool on your computer:
SET command="%ProgramFiles(x86)%\Microsoft SDKs\Windows\v6.0A\bin\xsd.exe" 
4. Click OK, and then close the Properties dialog.

Note - you may find there are multiple versions of the Xsd.exe tool on your computer. If you specify the path to a version that is not compatible with these steps, you may encounter an error in the Visual Studio IDE when you compile. If you get an error message related to the Xsd.exe tool, try changing the path specified in the pre-build event, so that it points to a different version of the Xsd.exe tool on your computer.

Building and Deploying the SearchMigrationTool Solution

Once you have completed the steps in the previous section, Installing and Configuring the SearchMigrationTool Solution, you can compile the solution by selecting Build Solution from the Build menu in the Visual Studio IDE.

Troubleshooting Build Errors with the SearchMigrationTool Solution

If the solution build task fails, and it's not clear what the initial cause of the failure was, try building the projects individually, in the following order:
  1. Common
  2. O12
  3. O14
  4. FS14Layer
  5. SearchMigrationTool
  6. Setup_x64
  7. Setup_x86
This approach should help pinpoint the source of the error, making it easier to resolve.

The setup projects, Setupx64 and Setupx86 do not include required functionality for the tool, so if either of these projects is the source of the error preventing the solution from compiling, you can remove the project from the solution, then re-build the solution.
To remove a setup project and rebuild the solution
  1. In Solution Explorer, right-click on the project that's failing to build, and click Remove.
  2. Click OK on the confirmation dialog.
  3. From the Build menu, click Rebuild Solution.

The setup projects build installers that you can use to deploy the SharePoint Enterprise Search Migration tool; however you can deploy the tool without using these installers by copying the assemblies required for the tool to the server where you need to run the tool.
The assemblies you need to copy are:
  • Common.dll
  • FS14Layer.dll
  • O12Layer.dll
  • O14Layer.dll
  • SearchMigrationTool.exe

You can find the required assemblies that you need to copy in the following locations:
Debug configuration
\SearchMigration\Build\Debug\SearchMigrationTool\
Release configuration
\SearchMigration\Build\Release\SearchMigrationTool\

See How to: Set Debug and Release Configurations for more information about the Debug and Release configurations in Visual Studio.

Using the SharePoint Enterprise Search Migration Tool

The Search service application must be on the server where the tool is run. If you are importing/exporting data from site collections, the server where you run the tool must be in the same farm as the site collections being accessed. If the Search service application is in the publishing farm, (parent farm in Office SharePoint Server 2007), and the site collections are in the consuming farm, (child farm in Office SharePoint Server 2007), then you should run the tool on the server in the consuming farm where the Search service application proxy is located.

The user account that you run the tool as must have sufficient permissions to administer site collections and the Search service application.

To run the tool, open an elevated command prompt on the server and navigate to where the tool is installed. If you manually deployed the tool by copying the required assemblies to the server, this is the folder that you copied them to. If you used the installer, the tool is installed in the following location:
%Program Files%\Microsoft\Search Migration Tool v1.1.1

The migration tool syntax is as follows:
searchmigrationtool.exe -action [-objectKind] [-filter=value] [-conflictBehavior=value] [-fastSearch] filename

Arguments

The SearchMigrationTool.exe takes the following arguments:
  • action
  • objectKind
  • filter
  • conflictBehavior
  • fastSearch
  • fileName
action
Required. Specifies the action performed by the tool. Must be one of the following:
  • Import
Imports the search objects. This action is supported only for SharePoint Server 2010 and FAST Search Server 2010 for SharePoint.
  • Export
Exports the search objects. This action is supported for Office SharePoint Server 2007, SharePoint Server 2010, and FAST Search Server 2010 for SharePoint.
  • saveSample
Saves an example of the input/output XML file that is generated by the tool.
  • saveSchema
Saves the XML schema describing the format of the input/output XML file that is generated by the tool.
objectKind
Required if you specify Import or Export for the action argument. Specifies the search data that the Import or Export actions apply to. Possible values include the following:
  • Bestbet
Specifies that keywords, best bets and synonyms are imported/exported.
  • Scope
Specifies that search scopes, scope rules and scope display groups are imported/exported.
  • Searchsettings
Specifies that search settings, such as the search center URL, dropdown mode, and the search results URL are imported/exported. This value is not supported for Office SharePoint Server 2007. If you specify this value when running the tool on Office SharePoint Server 2007, it will be ignored.
  • All
Specifies that everything is imported/exported.
filter
Optional. Specifies the sites or Search service applications that the action applies to, depending on the filter you choose, as follows:
  • siteFilter
Specifies the sites or site collections the action applies to.
  • searchAppFilter
Specifies the Search service applications the action applies to.

The filter value matching uses regular expressions. For more information on regular expressions, see .NET Framework Regular Expressions.

Following are some filter argument examples:
siteFilter=http://sharepoint
Matches http://sharepoint and http://sharepoint/sites/test, but not http://test/sites/sharepoint.

searchAppFilter=search.[12]
Matches the Search service application named Search 1, but not the Search service application named Search 3.
conflictBehavior
Specifies how the tool should handle existing search data that conflict with the search data being imported. Can be set to one of the following values:
  • continue
Specifies that when there is a conflict, an error is logged, and the existing search data is not modified. This is the default value.
  • overwrite
Specifies that when there is a conflict, the existing search data is overwritten with the data being imported.
  • prompt
Specifies that when there is a conflict, the tool will prompt the user to select whether to overwrite the existing data, or continue without modifying the existing data. This option may require extended monitoring while the tool is running on a large farm.
fastSearch
Optional. This is only supported when you specify Import for the action argument. Specifies that the Import action is done using the FAST Search Server 2010 for SharePoint administration interface.
fileName
Required. Specifies the input or output file that for the action specified.

To display the command syntax and options for the tool, run it without specifying any arguments as follows:
SearchMigrationTool.exe

Examples

Following are some usage examples for the SharePoint Enterprise Search Migration tool:
searchmigrationtool -export -scope -siteFilter=http://sharepoint C:\filename.xml
searchmigrationtool -export -scope -bestbet C:\filename.xml
searchmigrationtool -import -bestbet -conflictBehavior=prompt C:\filename.xml
searchmigrationtool -saveSample C:\sample.xml
searchmigrationtool -saveSchema C:\schema.xsd

Troubleshooting Steps

Use the following information to help troubleshoot problems when running the SharePoint Enterprise Search Migration tool.
  1. When importing data, ensure that the XML refers to the farm you want to import the data into. This usually means that you need to edit the XML file that you exported to replace all instances of a site collection URL or Search service application name. When doing that, ensure the text editor you are using can properly edit Unicode files, or else the xml file might be corrupted and any non-ascii characters present in the file might be replaced by the wrong characters.
  2. Ensure that you are specifying the correct path for the XML file. You must either specify an absolute path, or just the file name. You also need to confirm that you have sufficient permissions to create or read files from the location you specify for the XML file.
  3. Ensure that you, (or the user running the tool) has access to the site collection the tool is running against. To verify that you have access to the site collection, from a browser, open the following page: http://<SiteCollectionName>/_layouts/listkeywords.aspx. If you can view this page, you have sufficient access to the site collection.
  4. Ensure that you, (or the user running the tool) has access to the Search service application the tool is running against.
To verify that you have access to the Search service application
    1. On the Home page of the SharePoint Central Administration Web site, in the Application Management section, click Manage service applications.
    2. On the Manage Service Applications page, click Search Service Application.
If you can see the Search Administration page, you have access to the Search service application.
Last edited Aug 4 2010 at 7:11 AM  by davidreis, version 54
Updating...
Page view tracker