Home Library Learn Samples Downloads Support Community Forums
1 out of 1 rated this helpful - Rate this topic

SharePoint Enterprise Search Migration Tool for SharePoint Server 2010

SharePoint 2010

Updated: August 2010

Summary:  Use the SharePoint Enterprise Search Migration Tool when you upgrade to SharePoint Enterprise Search to migrate search-related data, such as best bets, search scopes, and site collection search settings.

Applies to:  Microsoft FAST Search Server 2010 for SharePoint | Microsoft SharePoint Server 2010 | Microsoft Office SharePoint Server 2007

Provided by:  David Reis de Sousa, Microsoft Corporation | Keller Smith, Microsoft Corporation | Jo-Anne Stamerjohn, Microsoft Corporation

Contents

Click to get code  Download code: SharePoint Enterprise Search Migration Tool

SharePoint Enterprise Search Migration Tool Overview

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 to perform manually.

To simplify this process, you can use the SharePoint Enterprise Search Migration Tool for Microsoft SharePoint Server 2010 to programmatically export and import search-related data between Office SharePoint Server 2007, SharePoint Server 2010, and FAST Search Server 2010 for SharePoint.

Table 1 lists the migration paths that are supported by the SharePoint Enterprise Search Migration Tool.

Table 1. Supported migration paths for the SharePoint Enterprise Search Migration Tool

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 SharePoint Enterprise Search Migration Tool can migrate the following search data:

  • Best bets

  • Search scopes

  • Site collection search center URL

  • Site collection search dropdown mode

  • Search results page URL

You can also modify the SharePoint Enterprise Search Migration Tool sample code to extend the functionality to migrate additional search data.

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 the SharePoint Enterprise Search Migration Tool source code

  1. On the Downloads tab of the resource page, download Source.zip.

  2. Extract the contents to a folder on your computer.

  3. Open the SearchMigrationTool solution in Microsoft Visual Studio.

    note Note:

    The SearchMigrationTool solution was created by using Microsoft Visual Studio 2008. If you are using a newer version of Microsoft Visual Studio you will have to run the Visual Studio Conversion wizard.

Projects in the SearchMigrationTool Solution

The Visual Studio solution for the SharePoint Enterprise Search Migration Tool, SearchMigrationTool, contains the following projects:

  • Common

  • SearchMigration

  • O12Layer

  • O14Layer

  • FS14Layer

The following sections describe each project in more detail.

Common Project in the SearchMigrationTool Solution

The Common project contains all the shared code for the SharePoint Enterprise Search 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 XML file or output XML file, provided as a reference.

  • XmlInputFileSchema.xsd   Defines the XML schema for the input XML file or output XML file.

  • XmlValidator.cs   Contains the class to use to validate the input XML file or output XML file against the XML schema.

SearchMigration Project for the SearchMigrationTool Solution

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

O12Layer Project for the SearchMigrationTool Solution

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

O14Layer Project for the SearchMigrationTool Solution

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

FS14Layer Project for the SearchMigrationTool Solution

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

Setup_x64

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

Setup_x86

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

Reference Assemblies for the SearchMigrationTool Solution

The SearchMigrationTool solution contains projects that reference assemblies from Office SharePoint Server 2007 and SharePoint Server 2010. To compile the solution, ensure that both versions of the assemblies are available. If you are compiling the solution on a computer that does not have either version installed, copy the assembly files to a local folder. Table 2 lists the reference assemblies, and the location that is configured for them in the project.

Table 2. Reference assemblies for the SearchMigrationTool Solution

Product Version Assembly

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 path %ProgramFiles(x86)%\Microsoft SDKs\Windows\v6.0A\bin\xsd.exe for the Xsd.exe tool. If the Xsd.exe tool location is different on your computer, change the path that is specified in the pre-build event.

To change the path specified for the Xsd.exe tool

  1. In Solution Explorer, right-click the Common project, and then click Properties.

  2. In the Properties dialog box, on the Build Events tab, click Edit Pre-Build.

  3. In the Pre-build Event Command Line text box, update the path in the line that contains the following SET command so that it specifies 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 box.

note Note:

You may find 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 could get 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 that is 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

After you complete the steps in the previous sections, you can compile the solution by selecting Build Solution on the Build menu in the Visual Studio IDE.

Troubleshooting Build Errors with the SearchMigrationTool Solution

If the solution build task fails, and it is not clear what the initial cause of the failure is, try building the projects individually, in the following order:

  1. Common

  2. O12Layer

  3. O14Layer

  4. FS14Layer

  5. SearchMigrationTool

  6. Setup_x64

  7. Setup_x86

This approach should help identify the source of the error, so that you can resolve it more easily.

The setup projects, Setup_x64 and Setup_x86, do not include any functionality that the tool requires to run. Therefore, if either of these projects is the source of the error that is preventing the solution from compiling, you can remove the project from the solution, then rebuild the solution.

To remove a setup project and rebuild the solution

  1. In Solution Explorer, right-click the project that is failing to build, and then click Remove.

  2. In the confirmation dialog box, click OK.

  3. On 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 that the tool requires to the server where you will run the tool.

The following are the required assemblies to copy:

  • Common.dll

  • FS14Layer.dll

  • O12Layer.dll

  • O14Layer.dll

  • SearchMigrationTool.exe

You can find the required assemblies to copy in the following locations:

Debug configuration
\SearchMigration\Build\Debug\SearchMigrationTool\

Release configuration
\SearchMigration\Build\Release\SearchMigrationTool\

For more information about the Debug and Release configurations in Visual Studio, see How to: Set Debug and Release Configurations.

Using the SharePoint Enterprise Search Migration Tool

The Search service application must be installed on the server where the tool is run. If you are importing data from or exporting data to site collections, the server where you run the tool must be in the same farm as the site collections that are being accessed. If the Search service application is in the publishing farm (the parent farm in Office SharePoint Server 2007), and the site collections are in the consuming farm (the child farm in Office SharePoint Server 2007), 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 use to run the tool 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 the path 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 at 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

Table 2 lists the command-line arguments for the SharePoint Enterprise Search Migration Tool.

Table 2. SharePoint Enterprise Search Migration Tool arguments

Argument Description

action

Required. Specifies the action performed by the tool. Must be one of the following:

  • Import   Imports the search objects. This action is supported for only SharePoint Server 2010 and FAST Search Server 2010 for SharePoint.

  • Export   Exports the search objects. This action is supported for Office SharePoint Server 2007, and SharePoint Server 2010.

  • saveSample   Saves an example of the input or output XML file that is generated by the tool.

  • saveSchema   Saves the XML schema that describes the format of the input or 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 or exported.

  • Scope   Specifies that search scopes, scope rules, and scope display groups are imported or exported.

  • Searchsettings   Specifies that search settings, such as the search center URL, search 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 is ignored.

  • All   Specifies that everything is imported or 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 that the action applies to.

  • searchAppFilter
    Specifies the Search service applications that the action applies to.

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

The following are examples of filter arguments:

  • 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 conflicts with the search data that is 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 that is 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 supported only when you specify Import for the action argument. Specifies that the Import action is done by using the FAST Search Server 2010 for SharePoint administration interface.

fileName

Required. Specifies the input or output file for the action specified.

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

SearchMigrationTool.exe

Usage Examples

The 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 for Running the SharePoint Enterprise Search Migration Tool

Use the following information to help troubleshoot problems when running the tool.

  1. When importing data, ensure that the XML in the input file points to the farm into which you want to import the data. This usually means that you have to edit the XML file that you exported to replace all instances of a site collection URL or Search service application name. When you edit the file, ensure the text editor you are using can properly edit Unicode files, or the XML file could become corrupted and any non-ASCII characters present in the file would be replaced by the wrong characters.

  2. Ensure that you (or the user running the tool) have access to the site collection and Search service application that the tool is running against, by using the following steps:

    To verify that you have access to the site collection

    1. From a web browser, open the following page:

      http:// <SiteCollectionName> /_layouts/listkeywords.aspx

      If you can view this page, you have sufficient access to the site collection.

    To verify that you have access to the Search service application

    1. On the home page of the SharePoint Central Administration 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.

  3. Ensure that you are specifying the correct path for the input or output XML file. You must either specify an absolute path, or just the file name. In addition, confirm that you have sufficient permissions to create files or read files from the location that you specify for the XML file.

Conclusion

When you upgrade SharePoint Enterprise Search by using the database attach approach, search-related data (such as best bets, search scopes, and site collection search settings) is not migrated automatically. Instead of performing this migration manually, you can simplify this process by using the SharePoint Enterprise Search Migration Tool to migrate this search-related data from the old farm to the new farm programmatically.

Additional Resources

Change History

 

Date Description

August 2010

For Table 2, in Export argument, removed reference to action support for FAST Search Server 2010 for SharePoint.

August 2010

Initial publication
Did you find this helpful?
(1500 characters remaining)

Community Additions

ADD
© 2013 Microsoft. All rights reserved.