PowerShell HowTo: Deploying a Custom Indexing Connector to SharePoint - Part 2

Deploying a custom indexing connector in SharePoint requires two steps:

• Adding a protocol used by SharePoint to call into the indexing connector
• Registering the indexing connector with SharePoint

In an earlier post we already covered step one and added a protocol to SharePoint. Now it's time to tell SharePoint about our indexing connector. The connector and the protocol will be associated together with the Business Data Catalog (BDC) model file.

Register the indexing connector with SharePoint

The cmdlet used to register the connector is New-SPEnterpriseSearchCrawlCustomConnector which takes our previously registered protocol as parameter as well as the path to the BDC model file. The model file describes the structure of the external system's data. It also contains information about where to find our indexing connector. The connector will be used to handle URLs starting with the given protocol.

     
Function RegisterCustomConnector
{
    param ([Microsoft.Office.Server.Search.Administration.SearchServiceApplication] $ssa, [string] $protocol, [string] $displayName, [string] $modelFilePath) 
    Write-Host "Registering custom connector: $displayName"
    $connector = New-SPEnterpriseSearchCrawlCustomConnector -SearchApplication $ssa -protocol $protocol -ModelFilePath $modelFilePath -Name $displayName
    if ($connector)
    {
      Write-Host -f Green "Successfully registered custom connector: $displayName"
    } else
    {
      throw "Registering custom connector failed: $displayName"
    }
}

$ssa = Get-SPEnterpriseSearchServiceApplication
RegisterCustomConnector -ssa $ssa -protocol "protocol1" -displayName "Connector" -modelFilePath "MyBDC.xml"

The documentation states that the protocol must have the format "protocol1://", but using just "protocol1" (without "colon dash dash") works just fine.

Example of a BDC model file where you can see the assembly and classes specified:

     
<Model name="MyModel" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.microsoft.com/windows/2007/BusinessDataCatalog">
  <LobSystems>
    <LobSystem name="ContosoSystem" type="Custom">
      <Properties>
        <Property name="SystemUtilityTypeName" type="System.String">ConnectorNamespace.ContosoSystemUtility, ConnectorAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0000000000000000</Property>
        <Property name="InputUriProcessor" type="System.String">ConnectorNamespace.ContosoLobUri, ConnectorAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0000000000000000</Property>
        <Property name="OutputUriProcessor" type="System.String">ConnectorNamespace.ContosoNamingContainer, ConnectorAssembly, Version=1.0.0.0, Culture=neutral, PublicKeyToken=0000000000000000</Property>
      </Properties>
      <!-- More content here -->
    </LobSystem>
  <!-- and here -->
  </LobSystems>
<!-- and here -->
</Model>

The assembly here is "ConnectorAssembly" which you have to deploy to the Global Assembly Cache (GAC).

(More about attributes used in the BDC model file can be found in the MSDN: "Search Properties for BDC model files".)

PowerShell HowTo: Deploying a Custom Indexing Connector to SharePoint - Part 1

Deploying a custom indexing connector in SharePoint requires two steps:

• Adding a protocol used by SharePoint to call into the indexing connector
• Registering the indexing connector with SharePoint

In this post I will show how to accomplish the first step via PowerShell.

Both steps are also described in the MSDN but we go one step further and automate it completely using PowerShell.

Adding protocol and handler to the registry

Based on the protocol of a content source's start address (e.g. http or bdc3) SharePoint decides which indexing connector should crawl it. The protocols known to SharePoint are stored in the Registry on the server where the crawling will take place.

So, the protocol used by our indexing connector also needs to be added to the registry. The following script adds the protocol protocol1:

        
Function RegisterProtocolHandler
{
    param ([string] $protocol)
    
    $path = "HKLM:\SOFTWARE\Microsoft\Office Server\14.0\Search\Setup\ProtocolHandlers\"
    Write-Host "Adding protocol handler to registry: $protocol" 
    # creates the property if not present, otherwise updates it
    Set-ItemProperty -path $path -name $protocol -value "OSearch14.ConnectorProtocolHandler.1" -ErrorAction Stop
    Write-Host -f Green "Successfully added protocol handler to registry: $protocol"
} 

RegisterProtocolHandler -protocol "protocol1" 

If you look at the registry afterwards you will see your protocol among the already registered ones:

HKLM:\SOFTWARE\Microsoft\Office Server\14.0\Search\Setup\ProtocolHandlers

But where to get the name of the protocol from in the first place? It has to be included in the documentation of the indexing connector you want to deploy. This is decided by the creator of the indexing connector and could basically be anything like protocol1, abc or helloworld.