Getting Started with Custom Enterprise Search Web Parts

This topic addresses the prerequisites for developing Enterprise Search custom Web Parts.

Developing Web Parts

Web Parts in Windows SharePoint Services 3.0 improve upon earlier versions of Web Parts technologies. You can use Windows SharePoint Services 3.0 Web Parts as well as Microsoft ASP.NET 2.0 Web Parts.

The base class provides basic properties that are common to all Web Parts, such as Title, Description, and so forth. You can add custom properties to your derived class and, at run time, the two sets of properties are presented and run as a single set of properties.

In essence, a Web Part is a .NET Web custom control assembly that uses a Web Part description file in either the Windows SharePoint Services format (.dwp) or the ASP.NET 2.0 format (.webpart). The Web Part description file can be stored on and referenced from any computer, and contains XML metadata that describes an instance of the Web Part. The Web Part .NET assembly is a DLL that must be installed and registered on each Windows SharePoint Services computer that uses the Web Part.

Choosing Between ASP.NET and SharePoint Web Parts

In general, you should design new Web Parts that inherit from the ASP.NET 2.0 WebPart class. ASP.NET Web Parts have description file names that use the .webpart extension. ASP.NET Web Parts provide the greatest flexibility and compatibility with Web sites that are not tightly coupled with Windows SharePoint Services.

Windows SharePoint Services 3.0 Web Parts provide backward compatibility with Windows SharePoint Services 2.0. SharePoint Web Parts have description file names that use the .dwp extension. SharePoint Web Parts include additional functionality but can be used only in a SharePoint site. Following is a list of the added features of SharePoint Web Parts.

• Cross-page connections in SharePoint sites

• Connections between Web Parts that are outside of a Web Part zone

• Client-side connections using the Web Part Page Services Component

• Web Part data caching

• Asynchronous processing using Web Part work items

For more information about developing and connecting Web Parts, importing an ASP.NET Web Part to a Windows SharePoint Services site, and the SharePoint Web Part object model, see the Microsoft Windows SharePoint Services 3.0 SDK.

Using the Query Object Model

Enterprise Search provides an object model that you can use to execute search queries programmatically against the search component. The Microsoft.Office.Server.Search.Query namespace includes two classes that provide this functionality:

• FullTextSqlQuery: Use this class for Enterprise Search SQL Syntax Reference search queries.

• KeywordQuery: Use this class for Enterprise Search Keyword Syntax Reference search queries.

For more information about using the Enterprise Search Query object model, see Getting Started with the Enterprise Search Query Object Model.

Setting Up the Development Environment

The supported approach for setting up your Web Part development environment is to develop locally on an Office SharePoint Server 2007 server.

You can use Microsoft Office SharePoint Designer 2007 to import Web Parts to Web pages, but not to create new Web Parts. To develop a custom Web Part assembly, you need to use a development tool such as Microsoft Visual Studio 2005. With Visual Studio 2005, you benefit from a rich development environment and debugging features. For more information about using Visual Studio 2005 for creating Web Parts, see the following:

• Microsoft Visual Studio 2005 Web Project System: What Is It and Why Did We Do It?

• ASP.NET Web Parts in Visual Studio

Creating the Web Part Project

You can use the Web Control Library template to create the Visual Studio 2005 project for your Web Part. This template is located in the New Project dialog box, in the Windows node for both C# and Visual Basic.

Project References

The project created from the Web Control Library template includes references to the assemblies required for an ASP.NET Web Part. However, because you will use the Enterprise Search Query object model to access the search component, you must add references to your project for certain assemblies.

Because you are using the Enterprise Search Query object model, you must include a reference to the Microsoft.Office.Server.Search.dll. Other assembly references in the following list are optional, but in most scenarios when you are working with the Enterprise Search Query object model you will need them as well.

Add the following references to your project:

• Microsoft.SharePoint.dll

  This assembly is required if your custom Web Part class is inheriting from the Microsoft.SharePoint.WebPartPages.WebPart class. It also may be required if you need to use the SPFarm object to programmatically retrieve information about the server hosting the Web Part.

• Microsoft.Office.Server.dll

  This assembly may be required if you need to use the Office Server Administration object model to programmatically retrieve information about the Shared Services Provider for the search component.

• System.Data.dll

• System.XML.dll

Creating the Web Part Class

You create the Web Part class by modifying the default class that is created from the Web Control Library template. The modifications you make depend on whether you are creating an ASP.NET Web Part or a SharePoint Web Part. These modifications are explained in the following sections.

You will also need to add the using namespace directive for Microsoft.Office.Server.Search.Query to the classes for both types of Web Parts. Following is the syntax to use:

using Microsoft.Office.Server.Search.Query;

Modifications for an ASP.NET Web Part

In addition to the Query namespace, you must also add the namespace directive for the ASP.NET Web Part class. Following is the syntax to use:

using System.Web.UI.WebControls.WebParts;

Modifications for a SharePoint Web Part

In addition to the Query namespace, you must also add the namespace directive for the SharePoint Web Part class. Following is the syntax to use:

using Microsoft.SharePoint.WebPartPages;

If you are creating a SharePoint Web Part, you also need to specify the XML Root namespace for your Web Part. Following is the syntax to use:

...
using Microsoft.SharePoint.WebPartPages:
namespace CustomSearchWebPart
{
    [XmlRoot(Namespace = "CustomSearchWebPart")]
    public class customSearchQuery : WebPart
...

Deploying the Web Part

When you compile your project, you have the option of strong naming your Web Part's assembly. If you are deploying the Web Part to the global assembly cache, you must strong name the assembly. If you are not deploying it to the global assembly cache, and are instead deploying it the _app_bin directory for the Office SharePoint Server 2007 site, strong naming the assembly is optional.

For more information about strong naming Web Part assemblies and deployment locations, see Managing Web Parts on Virtual Servers.

After you compile your Web Part, you can create the files you need to deploy it. For SharePoint Web Parts, you create a .dwp file; for ASP.NET Web Parts, you create a .webpart file.

Creating a .dwp File

You can create and edit a simple .dwp file using a text editor such as Notepad. The following code example shows the XML syntax for a simple SharePoint Web Part, without a strong name:

<?xml version="1.0"?>
<WebPart xmlns="https://schemas.microsoft.com/WebPart/v2">
   <Assembly>CustomWebPart, Version=1.0.0.0, Culture=Neutral, PublicKeyToken=null</Assembly>
   <TypeName>CustomWebPart.customSearchQuery</TypeName>
   <Title>Custom Search Web Part</Title>
</WebPart>

For more information about creating these files, see the following:

• Creating a Basic Web Part

• A Developer's Introduction to Web Parts

• Packaging and Deploying Web Parts for Microsoft Windows SharePoint Services

Creating a .webpart File

You can manually create and edit a simple .webpart file using a text editor such as Notepad. The following code example shows the XML syntax for a simple Web Part, without a strong name:

<?xml version="1.0" encoding="utf-8"?>
<webParts>
  <webPart xmlns="https://schemas.microsoft.com/WebPart/v3">
    <metaData>
     <type name="CustomASPNETWebPart.customSearchQuery, CustomASPNETWebPart, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />
      <importErrorMessage>Cannot import this Web Part.</importErrorMessage>
    </metaData>
    <data>
      <properties>
        <property name="Title" type="string">Custom Search Query</property>
      </properties>
    </data>
  </webPart>
</webParts>

You can also dynamically generate the .webpart file by exporting your Web Part from an ASP.NET page.

Registering and Importing Your Web Part as a SafeControl

Before you can use your Web Part in your site, you must register it in the SafeControl list and then import it into your site.

To register your Web Part in the SafeControl list

1. Open the web.config file located in the root folder for your site.

2. Locate the SafeControls tag.

3. Add a tag for your Web Part.

The following code example shows the tag syntax for a simple Web Part, installed in the BIN directory, without a strong name:

<SafeControl Assembly="CustomSearchWebPart, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"
 Namespace="CustomSearchWebPart" TypeName="*" Safe="True" />

Your final deployment step is to import the Web Part into your site.

To import a your Web Part into a site

1. In your browser, open the page you want to add the Web Part to, click the Site Actions menu, and then click Edit Page.

2. After the page is in Edit mode, click Add a Web Part for the Web Part zone you want, right or left.

3. In the Add Web Parts dialog box, click the Advanced Web Part gallery and options link.

4. Click Browse, and then click Import.

5. Click Browse, navigate to the location where you saved the .dwp or .webpart file, select it, and then click Open.

Your Web Part should now be listed in the dialog box. You can drag the Web Part from the dialog box onto the page.

See Also

Tasks

Walkthrough: Creating a Custom Enterprise Search Web Part
Walkthrough: Creating an ASP.NET Web Part for the AdventureWorks Business Data Application Sample

Concepts

Building Custom Enterprise Search Web Parts