Step 3: Deploy the Custom Web Part

Step 3 describes how you can deploy and register the custom federated search results Web part. It also discusses a security issue you should consider before deploying the Web Part.

The sample Web Part described in this walkthrough will work for federated locations configured to use the following per-user authentication types:

• Basic authentication

• Digest authentication

• NTLM authentication

Following are the basic steps to deploy the project:

• Give the CustomFederatedResultsSample assembly a strong name, and then build it.

• Install the CustomFederatedResultsSample assembly in the global assembly cache.

• Create a .dwp file for the CustomFederatedResultsSample Web Part.

• Register the CustomFederatedResultsSample Web Part as a safe control.

• Add the CustomFederatedResultsSample Web Part to the search results page.

You can download the complete code for the custom federated search results Web Part sample from the Custom Federated Results Web Part Sample release tab, on the Microsoft Office SharePoint Server 2007 SDK Search Samples resource page of the MSDN Code Gallery.

Security Considerations

The custom federated search Web Part described in this sample provides a user interface (UI) for the user to enter user credentials and submit them back to the server. After the user clicks the Logon button, the credentials are passed in the request back to the server in clear text. In this scenario, we recommend that you use Secure Sockets Layer (SSL) to secure the communication between the client browser and the Web server.

After receiving the credentials, the sample Web Part encrypts the values and stores them in cookies, which are passed between the client browser and the Web server for each subsequent request. Because of this, you should configure SSL for the site and not just for the initial logon.

To use SSL connections on your Web server, you must configure the server with a certificate from a recognized certification authority. For information about server certificates, see Obtaining Server Certificates.

For more information about configuring SSL, see the following resources:

• Plan for Secure Communication Within a Server Farm (Office SharePoint Server)

• Create a Web Application

• Plan Authentication Methods (Office SharePoint Server)

• How to: Set Up SSL on a Web Server

• Configuring SSL on a Web Server or Web Site

Procedures

To strong-name the assembly and build it

1. With the CustomFederatedResultsSample project open in Microsoft Visual Studio 2008, on the Project menu, click CustomFederatedResultsSample Properties.

2. On the Signing tab, select the Sign the assembly check box.

3. In the Choose a strong name key file list, click New.

4. In the Create Strong Name Key dialog box, for Key file name, type a name for your key file, and then click OK. If you have an existing key file to use, click Browse instead of New for this step, and then locate the existing file.

5. On the Build menu, click Build Solution.

For more information about this task, see How to: Sign an Assembly (Visual Studio). Alternatively, you can use Assembly Linker (AI.exe), which is available in the Microsoft .NET Framework SDK, to sign the assembly with a strong name as described in How to: Sign an Assembly with a Strong Name. For more information about strong-named assemblies, see Creating and Using Strong-Named Assemblies and Strong-Name Signing for Managed Applications.

After you sign your assembly with a strong name, you can install it in the global assembly cache. For more information, see How to: Install an Assembly into the Global Assembly Cache.

The following steps describe how to install the DLL to the global assembly cache by using the gacutil.exe command line utility. This utility is included with the Microsoft .NET Framework SDK. For more information, see Global Assembly Cache Tool (Gacutil.exe) and .NET Framework Tools.

To install the assembly in the global assembly cache

1. Click Start, point to All Programs, point to Microsoft .NET Framework SDK v2.0, and then click SDK Command Prompt.

2. At the SDK command prompt, type the following command.

   gacutil /if Path to Assembly\CustomFederatedResultsSample.dll 
   

   Replace Path to Assembly with the path to your DLL.

   Note

   When you use the /if switch, the tool overwrites the previous version of the assembly with the new version you are installing into the global assembly cache.

You also need to get the public key token value for the assembly.

To get the public key token value

1. In Windows Explorer, locate CustomFederatedResultsSample.dll in the path Local_Drive:\WINDOWS\assembly\.

2. Right-click the assembly, and then click Properties.

3. In the Properties dialog box, on the General tab, select and copy the token.

Now you can create the .dwp file for the CustomFederatedResultsSample Web Part. This XML file describes the Web Part, and you use it to import the Web Part into the Web Part gallery.

To create the .dwp file

1. Open a new file in a text editor, such as Notepad, and add the following XML code to the file.

   <?xml version="1.0"?>
   <WebPart xmlns="https://schemas.microsoft.com/WebPart/v2">
       <Assembly>CustomFederatedResultsSample, Version=1.0.0.0, Culture=Neutral, PublicKeyToken=PublicKeyTokenForYourWebPart</Assembly>
          <TypeName>CustomFederatedResultsSample.PerUserAuthWebPart</TypeName>
       <Title>Per User Authentication Federated Results</Title>
   </WebPart>
   

2. Replace PublicKeyTokenForYourWebPartAssembly with the actual public key token value for your Web Part's assembly.

3. Name the file CustomFederatedResultsSample.dwp, and then save it.

To register the Web Part as a safe control

1. Open the web.config file for the site you want to add the Web Part to. You can find this file in the root folder for the site. For more information about finding the web.config file for your site, see Working with Web.config Files and How to: Find the Web Application Root in the Windows SharePoint Services 3.0 SDK.

2. Add the following SafeControl element to the SafeControls section of the web.config file.

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

3. Replace PublicKeyTokenForYourWebPartAssembly with the actual public key token value for your Web Part's assembly.

4. Save your changes, and then close the web.config file.

5. Reset Internet Information Services (IIS). At a command prompt, type iisreset.

To add the Web Part to the search results page

1. Open the Search Center Results page in your browser, click Site Actions, and then click Edit Page.

2. Click Add a Web Part in the Right Zone.

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

4. Click Browse, and then click Import.

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

   You should now see the Per User Authentication Federated Results in the dialog box. You can drag it onto the page to use it.

6. In the Per User Authentication Federated Results, click the edit down arrow to display the Web Part menu, and then click Modify Shared Web Part.

7. In Location Properties, from the Location list, select the name of a federated location that you have configured to use NTLM authentication, Basic authentication, or Digest User authentication.

8. Click OK.

9. Click Site Actions, and then click Exit Edit Mode to close the Edit page.

See Also

Reference

FormsCredentials
FederatedResultsWebPart
FederatedResultsDatasource
FederatedResultsDatasourceView
SearchResultsBaseWebPart
SearchResultsBaseDatasource
SearchResultsBaseDatasourceView

Concepts

Step 1: Set Up the Project for the Custom Web Part
Step 2: Add the Code for the Custom Web Part
Creating a Custom Federated Search Web Part with a Credentials UI
Federated Search Overview