I posted a while back on how to do your Managed Property mappings in PowerShell, so I wanted to follow up with how to add search scopes next. I have to give props to the SDK team because they have done a pretty good job documenting all of these PowerShell commands. They even provide examples which I like a lot. When trying out command sto create scopes and their associated rules, I ran into a few things that I wanted to share. You will want to put all of these commands into a .ps1 script file. You can create your script file in PowerShell-ISE or just use notepad. We start out by getting a reference to the search application.
$searchapp = Get-SPEnterpriseSearchServiceApplication "Search Service Application"
At this point, we are ready to create a new scope. It’s pretty simple. To create a scope, we use the New-SPEnterpriseSearchQueryScope command. Here is my command to create a scope called My Scope. One thing to note here is that DisplayInAdminUI is a required parameter. It turns out you can create hidden scopes with PowerShell even though you can’t do it through the UI.
$scope = New-SPEnterpriseSearchQueryScope -Name "My Scope" -Description "My scope created in PowerShell" -SearchApplication $searchapp -DisplayInAdminUI $true
We now want to create scope rules for this scope. I assign the resulting object from the above command into a variable called $scope so that we can pass it to the scope parameter of the New-SPEnterpriseSearchQueryScopeRule command. When creating a scope rule through the UI, you have four choices: All Content, Property Query, Content Source, and Web Address. We’ll start with the simplest one, All Content. For this, we just specify a RuleType value of AllContent. All commands to create new scope rules require a URL. It’s not entirely clear what this URL does since it’s not something you enter in the UI when you create a rule. From the SDK, it simply states that it “specifies the results URL that is associated with the query rule.” I guess you could give it a path to the results page in your search center. For now, I just specify the path to the server and it seems to work.
New-SPEnterpriseSearchQueryScopeRule -RuleType AllContent -url http://sp2010 -scope $scope
Next, we’ll create a scope rule using the PropertyQuery Rule Type. It requires a few more parameters. TheManagedProperty parameter specifies the name of your managed property. In my example, I am going to use a property called Color. The PropertyValue parameter specifies the value. I want to see products that are red, so I’ll specify Red here. With any scope rule, you can specify whether the results from the rule should be Included, Required, or Excluded. We specify this with the FilterBehavior parameter. This parameter is required when using this PropertyType (note the SDK says it is optional). Also, when using a property query, the SearchApplication parameter is required too so just pass it the value $searchapp and it will work fine. Here is the command.
New-SPEnterpriseSearchQueryScopeRule -RuleType PropertyQuery -ManagedProperty Color -PropertyValue Red -FilterBehavior Include -url http://sp2010 -scope $scope -SearchApplication $searchapp
When you execute the command it gives you some basic info about the rule you set up as well as an estimated count.
Setting up a scope with a RuleType of Url took me a bit longer to figure out. This is because there is a parameter called UrlScopeType and the SDK didn’t say what value was expected there. I had to do some digging. The SDK, didn’t say what values it was expecting nor did the Get-Help command. I did some reflecting and finally found an enum that had the answer. The values it wants are Folder, HostName, orDomain. This of course makes sense when you go back and look at the UI and see the parameters you specify there.
The other parameter you need to know about here is MatchingString. You specify the value to the folder, hostname, or domain you want to use. In this case I am setting up a rule for a particular subsite.
New-SPEnterpriseSearchQueryScopeRule -RuleType Url -MatchingString http://sp2010/bcs -UrlScopeRuleType Folder -FilterBehavior Include -url http://sp2010 -scope $scope
So now we can create rules for all content, a web address, and a property query. However, if you have ever set up a scope before, you know there is one more type. That type is a content source. The SDK, didn’t have this type listed so I looked around in reflector again and found that we could specify a value ofContentSource for the RuleType parameter. However, when I tried to specify that parameter, it didn’t work. I took a look at the code and discovered that there is no code implemented to create a content source scope rule. After doing some experimenting in PowerShell, I did discover the answer, but I’ll save that for the next post where I will show you how I figured it out.
Remember you can add multiple rules at a time to one scope. Just put them all in one script file and run it. Also if you need to delete your Scope, you can use the Remove-SPEnterpriseSearchQueryScope command but you have to pass it an actual scope object which you can get with the Get-SPEnterpriseSearchQueryScope command. Here is how I deleted my scopes as I was testing.
$searchapp = Get-SPEnterpriseSearchServiceApplication "Search Service Application"
Get-SPEnterpriseSearchQueryScope -Identity "My Scope" -SearchApplication $searchapp | Remove-SPEnterpriseSearchQueryScope
You can do so much in SharePoint with PowerShell. This is just one more thing, I won’t have to manually configure any more. The SDK does a great job documenting all of the commands out there (although I would like to see that info on the UrlScopeType parameter added some time :) ). Try some of them out and you’ll be amazed at what you can accomplish.