Share via

Getting Started with the Enterprise Search Administration Object Model

  • Article

Enterprise Search in Microsoft Office SharePoint Server 2007 provides a new Search Administration object model that you can use to create custom applications to administer Enterprise Search programmatically.

The Enterprise Search Administration object model is implemented in the Microsoft.Office.Server.Search.Administration namespace, found in Microsoft.Office.Server.Search.dll.

You can write code that uses the Enterprise Search Administration object model from different types of applications, including from the following:

  • A console application

  • A custom search Web Part hosted in a SharePoint site

  • An ASPX Web application

  • A Windows Forms client application

Using the Search Administration Object Model

The following diagram details the major extensibility areas in the new Administration object model.

Search Administration Object Model

SearchContext Object

The Microsoft.Office.Server.Search.Administration.SearchContext object is the entry point to the Enterprise Search Administration object model. The GetContext method returns the search context for the site, server, or Shared Services Provider (SSP) that you specify. Depending on which method overload you use, you might need to also include a reference in your project to the Microsot.Office.Server.dll or to the Microsoft.SharePoint.dll. For more information about the GetContext method, see How to: Return the Search Context for the Search Service Provider.

Note

After you install Microsoft Office SharePoint Server 2007, you might need to restart the server that is hosting your SSP site before making any Enterprise Search Administration object model calls.

Performance Considerations

If you use the GetContext method overload of the SearchContext class to retrieve the search context, we recommend that your code instantiate the SPSite object within a using statement to ensure the object is released after it is no longer needed. The following is an example.

SearchContext context;
using (SPSite site = new SPSite("http://yourSiteName"))
{
     context = SearchContext.GetContext(site);
}

Content Sources

In Enterprise Search, content sources allow you to specify the content to crawl, how to configure the crawl, and when to schedule the crawl.

The top-level object in the content sources object model is the Content class. When you initialize an instance of the Content class, you pass a SearchContext object as a parameter in the constructor.

The ContentSources property of the Content class returns the content sources for an SSP, represented by a ContentSourceCollection object.

The base class that represents individual content sources is the ContentSource class. The object model also includes the following classes to represent the different types of content sources available in Enterprise Search.

  • HierarchicalContentSource
    Base class for hierarchical content sources, such as the FileShareContentSource and ExchangePublichFolderContentSource.

The content source object model also includes classes for managing the crawl schedule. Use the FullCrawlSchedule property of the ContentSource class to configure the full crawl schedule. Use the IncrementalCrawlSchedule property of the ContentSource class to configure the incremental crawl schedule.

The base class for crawl schedules is the Schedule class. The object model also includes the following derived classes that you use for configuring the crawl schedule.

  • DailySchedule
    Used to specify the number of days between crawls.
  • MonthlyDateSchedule
    Used to specify the days of the month and months of the year when the crawl should occur.
  • MonthlyDayOfWeekSchedule
    Used to specify the days of the month, the weeks of the month, and the months of the year when the crawl should occur.

For more information about content sources, see Managing Content.

Content Source Samples

For step-by-step, how-to procedures for programming content sources, see the following:

How to: Retrieve the Content Sources for a Shared Services Provider

How to: Add a Content Source

How to: Delete a Content Source

How to: Programmatically Configure a Crawl Schedule for a Content Source

How to: Programmatically Manage the Crawl of a Content Source

Metadata Property Schema

The Enterprise Search metadata property schema includes two types of properties: crawled properties, which are discovered by the search service index component when crawling content, and managed properties, which are managed by search administrators, and are explicitly set to be used in the search experience. You must map crawled properties to managed properties to use them in the search experience. For more information about properties in Enterprise Search, see Managing Metadata.

Managed properties are managed by administrators, and are explicitly set to be used by the query system. Map crawled properties to manage properties to create new properties to use for querying.

The entry point for managing metadata properties in the Administration object model is the Schema object. When you initialize an instance of the Schema class, you pass a SearchContext object as a parameter in the constructor. The AllManagedProperties property of the Schema class returns a ManagedPropertyCollection object that represents a collection of all the managed properties in the SSP's search schema. The ManagedProperty class represents a single managed property.

Crawled properties are grouped together into different categories, based on the protocol handler used. The AllCategories property of the Schema class returns a CategoryCollection object that represents all the crawled property categories in the SSP's search schema. The Category class represents a single crawled property category. Use the GetAllCrawledProperties method of the Category class to return an enumerator for the category's collection of crawled properties. The CrawledProperty class represents a single crawled property.

Schema Samples

For step-by-step, how-to procedures for programming with the Enterprise Search schema, see the following:

How to: Retrieve the Crawled Properties for a Category in the Search Schema

How to: Retrieve the Managed Properties for a Shared Services Provider

How to: Retrieve the Crawled Properties Mapped to a Managed Property

How to: Create a Managed Property

How to: Delete a Managed Property

How to: Map a Crawled Property to a Managed Property

Search Scopes

In Enterprise Search, search scopes represent a collection of items based on a common element or elements among the items within that scope. Scopes are defined by rules that are registered for that scope. There are global scopes configured at the SSP level, which are available to all sites configured to use that SSP. There are also site-level scopes, which are available only to the site and subsites for the site where they are configured.

Display groups are groupings of scopes, and can be used to manage which scopes appear with the scopes list for different search Web Parts, including the Advanced Search and Search Box Web Parts.

For more information about Enterprise Search scopes, see Working with Search Scopes.

The entry point for managing search scopes in the Administration object model is the Scopes class. When you initialize an instance of the Scopes class, you pass a SearchContext object as the parameter for the constructor.

The AllScopes property returns a ScopeCollection object that represents the collection of all the SSP's search scopes.

The AllDisplayGroups property returns a ScopeDisplayGroupCollection object that represents the collection of all the display groups in the SSP's scopes.

The Scope class represents a single search scope, and the ScopeDisplayGroup class represents a single display group.

Keywords and Best Bets

Keywords are words or phrases that are identified as important to the organization. They provide a way for search administrators to display additional information and recommended links on the initial results page. Keywords can be beneficial in the following scenarios:

  • When users frequently query for information that is not included in the content index.

  • When an organization needs to promote certain links, giving them a prominent place in search results.

For more information about keywords, best bets, and definitions, see Managing Keywords.

Enterprise Search keyword administration is performed at the site level. The top- level object in the keyword object model is represented by the Keywords class. The constructor for the Keywords class takes two parameters: a SearchContext object, which represents the SSP, and a System.Uri object, which represents the site URL.

The AllKeywords property of the Keywords class returns a KeywordCollection object that represents all the keywords for the specified site. Individual keywords are represented by the Keyword class. To access the actual keyword term or phrase, use the Term property of the Keyword class. The string that describes the keyword is stored in the Definition property.

Use the Synonyms property to return a SynonymCollection object that represents all the synonyms for the keyword. Use the BestBets property to return a BestBetCollection object that represents all the best bets for the keyword.

You can also access all the best bets defined for a site by using the GetAllBestBets method of the Keywords class. The BestBet class represents a single instance of a best bet, and individual synonyms are represented by the SynonymCollection class.

Ranking

Enterprise Search provides a relevance object model that you can use to customize the parameters used by the ranking engine. For more information about Search relevance, see Enterprise Search Relevance Architecture Overview.

Note

Changing the ranking parameter values arbitrarily can have an adverse effect on the overall relevance of the system. We do not recommend that you do this without carefully evaluating the changes and how they impact accuracy of search results.

The top-level object in the relevance object model is represented by the Ranking class. The constructor for the Ranking class takes one parameter: a SearchContext object, which represents the SSP.

The RankingParameters property of the Ranking class returns an object that represents all the ranking parameters for the SSP. You cannot add, remove, or rename ranking parameters in the collection; you can only modify the parameter values. Individual ranking parameters are represented by the RankingParameter class.

Use the AuthorityPages property to return an AuthorityPageCollection object that represents all the authority pages registered for the SSP.

Use the DemotedSites property to return a DemotedSiteCollection object that represents all the demoted sites registered for the SSP.

To start the ranking update process for an SSP, use the StartRankingUpdate method.

Propagation

If the index service and query service are running on separate servers, the Search service must copy the content index from the index service server to the query service server. The name for this process is propagation.

Enterprise Search provides you with the ability to access status information about the propagation system. The top-level object in the propagation object model is the Propagation class. When you initialize an instance of the Propagation class, you pass a SearchContext object as a parameter in the constructor.

To retrieve the status of the overall propagation system, use the Status property of the Propagation class.

To check the propagation status for individual query servers, first retrieve the query server's enumerator by using the QueryServers property of the Propagation class. Then, enumerate through the collection of query servers to retrieve the QueryServer object representing the query server.

Crawl Log

You use the LogViewer object to retrieve the crawl log data. The MaxDaysCrawlLogged property of the LogViewer class allows you to set the maximum number of days for the crawl log to retain data.

To manipulate the data in the crawl log, you use the CrawlLogFilters class, which contains all of the filters used for this purpose. This class contains an AddFilter method with four method overloads, allowing you to add filters for the following:

  • All integer properties (such as startAt, TotalEntries, and MessageId)

  • Log time

  • Message type

  • URL

See Also

Tasks

How to: Return the Search Context for the Search Service Provider

Reference

Microsoft.Office.Server.Search.Administration

Concepts

Enterprise Search Architecture
Managing Content
Managing Metadata
Working with Search Scopes
Managing Keywords
Enterprise Search Relevance Architecture Overview