Starting the SharePoint 2010 Foundation Search Service using PowerShell

It’s been a while since my last real SharePoint 2010 scripting post but we’re getting close to RTM so I figured I need to buckle down and play some catch up and get some long overdue posts published. So, continuing my series of posts on scripting the various services and service applications within SharePoint 2010 I decided that I would share something that I know a lot of people have been struggling with recently – scripting the SharePoint Foundation Search Service.

This one threw me for a bit of a loop because all the other services and service applications can be configured almost exclusively using PowerShell cmdlets – this one though has to be configured almost exclusively using the object model. We basically have four cmdlets available to help with the configuration and unfortunately they’re not much help at all:

Get-SPSearchService – Returns back an object representing the actual service

Get-SPSearchServiceInstance – Returns an object representing a service configuration for the service

Set-SPSearchService – Updates a few select properties associated with the service

Set-SPSearchServiceInstance – Updates the ProxyType for the service

The main failing with these cmdlets is that you can’t set the services process identity, the database name and server or failover server, and you can’t trigger the provisioning of the service instances which is required for the service to be considered fully "started". All of these things I can do through Central Admin but there’s no way to do it using any provided cmdlets – so how do we solve the problem? By getting our hands dirty and writing a boat load of code against the object model.

So let’s get started. As before we’ll use an XML file to drive the setup process:

As you can see the configuration file is pretty simple. We define two accounts that we’ll use, one for the process identity of the service and the other for the crawl account. There’s a few simple attributes for the database and some miscellaneous configurations and a list of all the servers in which the service should be started on.

Okay, let’s start digging into the actual script. The first thing I do is load the XML file to a variable, $svcConfig, which I use throughout the function:

1: $config = Get-Content $settingsFile

2: $svcConfig = $config.Services.FoundationSearchService

Line 1 loads the file into a System.Xml.XmlDocument typed variable and then I grab the <FoundationSearchService /> element and set that to the $svcConfig variable. Next I need to determine if the script should continue on this server by checking the <Servers /> element to see if there’s a match for the current machine:

The trick with this is that if we’re not using SharePoint Foundation then once the service is initially started it renames itself to "SharePoint Foundation Help Search" so I had to put a provision to look for one name or the other to allow this script to be run multiple times and from multiple machines. Now that the service is started lets set a few variables that we’ll use throughout the rest of the script:

1:#Get the service and service instance

2: $searchSvc = Get-SPSearchService

3: $searchSvcInstance = Get-SPSearchServiceInstance -Local

4:

5: $dbServer = $svcConfig.DatabaseServer

6: $failoverDbServer = $svcConfig.FailoverDatabaseServer

We’ll use the $searchSvc and $searchSvcInstance variables extensively. Note that we’ll also need to repeat lines one and two at least a couple of times to avoid update conflicts as a result of timer jobs modifying those objects.

The next step will be to set the process identity for the service. We’ll go ahead and also get the crawl account information while we’re at it to avoid prompting for passwords in more than one location:

1:#Get the service account details

2: Write-Host "Provide the username and password for the search crawl account..."

3: $crawlAccount = Get-Credential $svcConfig.CrawlAccount.Name

4: Write-Host "Provide the username and password for the search service account..."

This is where things start to get interesting. I use the Get-Credential cmdlet to return back the credentials of the user to use for the service but once I have that there’s no parameter on any cmdlet that will allow me to set the credential so I have to do it using the object model. I use the $searchSvc variable from earlier and edit the object returned by the ProcessIdentity property (after confirming that the value needs to be changed).

Once we have the process set we can go ahead and set the other simple properties on the service – fortunately the cmdlet Set-SPSearchService can actually help us out with this one:

1:#It doesn't hurt if this runs more than once so we don't bother checking before running.

Alright, that was the easy stuff – now we have to deal with the database. The first step is to see if there’s already a database defined for the service and if it matches what we want. This is important as we want to be able to run the script more than once so we don’t want to just blindly delete and recreate the database. The first bit of code builds a connection string using the SqlConnectionStringBuilder object (note that in PowerShell you have to use the PSBase property to access the properties on this object) and then compares that to what is currently set. If a match is not found then the existing database is deleted and the search service updated:

I first create a new SPSearchDatabase object by calling the static Create() method and passing in the SqlConnectionStringBuilder object that was previously created. I then call the Provision() method to actually create the database on the SQL server instance. Once it’s created we can associate the database with the service by setting the SearchDatabase property on the $searchSvcInstance variable. If an error occurs then I attempt to delete the database from SQL Server if it’s not yet associated with the service.

Now that we have our database provisioned we can go ahead and set the failover server:

Most of the logic here is just in determining whether or not to set the failover server. Basically you just call the AddFailoverServiceInstance() method of the SearchDatabase property (SPSearchDatabase) and then update the service instance.

We’re almost there – we’ve set all the properties we can now we need to complete the provisioning process:

If the service instance is not currently marked as Online (again, accounting for multiple runs) and the service instance we’re working with is for the current machine then we call the Provision() method on the service instance. If an error occurs provisioning the service then I try to set the status back to its previous value.

Only two steps left; First we need to create a timer job to trigger the search service instance to be provisioned on the other servers in the farm:

1:#Re-get the service to avoid update conflicts

2: $searchSvc = Get-SPSearchService

3:

4:#Create the timer job to update the instances for the other servers.

And finally, we need to set the ProxyType for the service instances so I loop through the <Server /> elements and call the Set-SPSearchServiceInstance cmdlet, providing the ProxyType attribute as defined in the XML:

#See if we want to start the svc on the current server. $install = (($svcConfig.Servers.Server | where {$_.Name -eq $env:computername}) -ne $null)if (!$install) { Write-Host "Machine not specified in Servers element, service will not be started on this server."return }

One thing you should note is that I’m not setting the schedule for the service. This is because the timer job class that I’d need to use to set the schedule is marked internal thus making it impossible for me to set the schedule without using reflection.

As you can see we’re in a bit of a conundrum with SharePoint 2010 – scripting your installations is considered to be a best practice and you should strive to do so whenever possible but the level of complexity involved with scripting such simple things has made it prohibitively complex for the average administrator to do.

I recognized this issue the very first day I started working with SharePoint 2010 and to solve the problem I’ve been working on a product for ShareSquared called SharePoint Composer which will allow administrators, architects, and developers to visually design their SharePoint configurations and then build out the entire Farm using the model they create in the design tool. This tool will allow you to enforce your corporate standards by clearly documenting every configuration and building the farm based on those configurations in a single-click, automated way – all without having to know any PowerShell at all! Keep a watch here for more information about SharePoint Composer.

Note – I’ve not had a chance to test this in a multi-server farm so if anyone can give me some feedback about their experiences with it I’d greatly appreciate it.

Yup – totally agree – the reason I’m trying to show how to do it with PS is because STSADM has been “marked” as deprecated – For this one particularly though, I suspect everyone will just use stsadm (it’s a shame really that msft officially says it’s deprecated but doesn’t give an equivalent (in terms of ease of use) alternative solution).

Hello Gary,
i would like to add this script to my AutoSpInstaller Script but i can’t see them.
Can i download this or have you another location?
At your old page, there i can see the script but i can download this!
Thanks Horst

Thanks for the heads up. Some of my posts didn’t come over properly when I migrated so thanks for helping me identify this one. As for the script – this example was more of an academic exercise showing how to create the service using pure PowerShell – for anything production you should use STSADM (my script works, but the complexity is a bit much).