Creating Enterprise Search Scopes with PowerShell

Posted Thursday, July 29, 2010 2:47 PM by CoreyRoth

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

EnterpriseSearchPowerShellNewScope

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

EnterpriseSearchPowerShellNewScopeRuleAllContent

Next, we’ll create a scope rule using the PropertyQuery Rule Type.  It requires a few more parameters.  The ManagedProperty 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

EnterpriseSearchPowerShellNewScopeRulePropertyQuery

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, or Domain. This of course makes sense when you go back and look at the UI and see the parameters you specify there.

 EnterpriseSearchPowerShellUIWebAddress

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

EnterpriseSearchPowerShellNewScopeRuleUrlFolder

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 of ContentSource 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.

Comments

# Twitter Trackbacks for Creating Enterprise Search Scopes with PowerShell - Corey Roth - DotNetMafia.com - Tip of the Day [dotnetmafia.com] on Topsy.com

Pingback from  Twitter Trackbacks for                 Creating Enterprise Search Scopes with PowerShell - Corey Roth - DotNetMafia.com - Tip of the Day         [dotnetmafia.com]        on Topsy.com

# re: Creating Enterprise Search Scopes with PowerShell

Sunday, August 8, 2010 8:36 PM by Peter

Hi Corey, thanks for this blog post, good stuf..

Do you know the powershell command/s to use to update the display groups after successfully creating a search scope?

Thanks,

Pete

# re: Creating Enterprise Search Scopes with PowerShell

Sunday, August 8, 2010 11:52 PM by CoreyRoth

@Peter I don't believe there is one.  I've got an idea though.  Give me a bit and I'll have something for you.

# re: Creating Enterprise Search Scopes with PowerShell

Monday, August 9, 2010 3:12 PM by CoreyRoth

@Peter  Ok, you inspired me.  I created some cmdlets to create scope display groups.  Check out the following post.

www.dotnetmafia.com/.../introducing-the-sharepoint-powershell-community-toolkit.aspx

# re: Creating Enterprise Search Scopes with PowerShell

Monday, August 9, 2010 4:18 PM by Peter

Thanks Corey.  This looks fantastic.  I'll give it a whirl.  What a turnaround!

# re: Creating Enterprise Search Scopes with PowerShell

Monday, August 9, 2010 6:50 PM by Peter

Corey, I downloaded the Codeplex tookit and tried it out, great stuff!  

I then went back and read your blog post on creating cmdlet's and had a crack myself at a couple for the toolkit if you'd like (and which have helped me out for my current work)...  I saw you noted them as possible Future Commands.   I've created : Remove-SPEnterpriseSearchQueryScopeDisplayGroupScope (simply removes a scope from a given display group) and Get-SPEnterpriseSearchQueryScopeDisplayGroup (returns a display group to work with).

Cheers

Pete

# re: Creating Enterprise Search Scopes with PowerShell

Monday, August 9, 2010 7:03 PM by CoreyRoth

@Peter That's excellent.  I was actually planning on writing those two commands tonight so thanks for saving me the time. :-)

I don't have the code set up in TFS yet, so if you want to just post the snippets to a discussion on CodePlex or ping me on twitter and I'll shoot you my E-mail address and I'll get them included in the build.

Thanks,

Corey (@coreyroth)

# re: Creating Enterprise Search Scopes with PowerShell

Monday, August 9, 2010 7:49 PM by Peter

Hi Corey, I've just added the code as a discussion on CodePlex... if you could run your eye over it and make any updates as you wish.

I made another small change to the New-SPEnterpriseSearchQueryScopeDisplayGroupScope cmdlet also, just to check if the scope already exists in the display group first.  I'll add this as a discussion item also.

// add the scope to the display group if it hasn't already been added

           if(!scopeDisplayGroup.Contains(scope))

               scopeDisplayGroup.Add(scope);

Thanks,

Pete

# Issues creating SharePoint 2010 search scopes programmatically at SharePoint Config

Pingback from  Issues creating SharePoint 2010 search scopes programmatically at SharePoint Config

# Creating SharePoint 2010 search scopes programmatically at SharePoint Config

Pingback from  Creating SharePoint 2010 search scopes programmatically at SharePoint Config

# re: Creating Enterprise Search Scopes with PowerShell

Wednesday, April 13, 2011 12:00 PM by Adalto

Hi.

Can I use PowerShell to copy all Shared Scopes from a Search Service App to another?

Thx

# re: Creating Enterprise Search Scopes with PowerShell

Wednesday, April 13, 2011 12:43 PM by CoreyRoth

Unfortunately, there isn't really a very direct way of copying scopes from one application to another using PowerShell.

# re: Creating Enterprise Search Scopes with PowerShell

Wednesday, April 13, 2011 1:28 PM by Adalto

=(

Did you do that? I don't know if I try a C# app or PowerShell or whatever =D

I just don't want to rewrite all those rules =/

Thx Roth

# re: Creating Enterprise Search Scopes with PowerShell

Wednesday, April 13, 2011 2:03 PM by CoreyRoth

I heard you.  I usually create scopes and property mappings with PowerShell to begin with so I can deploy them later.  Take a look at the SharePoint Enterprise Search migration tool to move scopes.

msdn.microsoft.com/.../ff828776.aspx

# FAST Search Scopes « Sladescross's Blog

Thursday, June 16, 2011 6:00 AM by FAST Search Scopes « Sladescross's Blog

Pingback from  FAST Search Scopes « Sladescross's Blog

# re: Creating Enterprise Search Scopes with PowerShell

Wednesday, October 19, 2011 10:43 AM by Girum Wl

Nice post. Thank you.

# re: Creating Enterprise Search Scopes with PowerShell

Wednesday, November 7, 2012 3:24 AM by Mate

Great help, saved my day! Thanks from the Nordic Countries!

# re: Creating Enterprise Search Scopes with PowerShell

Monday, January 14, 2013 10:13 PM by Graham

Great blog article, thanks.

I have an interesting issue when I tried to delete the 'All Sites' scope.  It won't.  Is this because its a default scope?  I have a suspicion its corrupt hence my need to delete it.

Thanks

# re: Creating Enterprise Search Scopes with PowerShell

Tuesday, January 15, 2013 2:13 PM by CoreyRoth

@Graham I don't believe that you can delete it so I think that is why you are seeing the issue.

Leave a Comment

(required)
(required)
(optional)
(required)