This is just a short post to supplement the “Working with Sitecore items in PowerShell Extensions” as we now have a new cmdlet of retrieving items in SPE 3.0.

Find-Item cmdlet allows you to leverage the glorious new search API Sitecore introduced in the 7.0 version of its CMS to retrieve items using the Sitecore Content Search indexes.

You will find the available parameters on it as follows:

• -Index – index name – ISE supports index name auto completion
• -Where – Dynamic Linq syntax as specified in this blog
• -WhereValues – array of objects for Dynamic Linq
• -Where parameter. -OrderBy – Dynamic Linq syntax ordering parameter
• -First – number of results to return -Skip – number of results to skip before returning the rest of results.
• -Criteria – simple search criteria in the following example form:

The Criteria syntax is similar to how you provide the extensible formatting for Format-Table, namely a hashtable array:

@{
    Filter = "Equals"
    Field = "_templatename"
    Value = "PowerShell Script"
}, 
@{
    Filter = "StartsWith"
    Field = "_fullpath"
    Value = "/sitecore/system/Modules/PowerShell/Script Library/System Maintenance"
}

Where Filter in the criteria allows for one of the following values:

• Equals
• StartsWith,
• Contains,
• EndsWith

Resulting in the following Syntax reported by PowerShell:

Find-Item [-Index] <string> [-Criteria <searchcriteria[]>] 
    [-Where <string>] [-WhereValues <Object[]>] 
    [-OrderBy <string>] [-First <int>] 
    [-Skip <int>]

When to use which parameters?

You might have noticed that there are 2 ways of filtering items.

• Using the -Criteria parameter,
• and using the -Where and -WhereValues parameters

This is due to the new capabilities introduced in Sitecore 7.5 which were not available before that version was released, namely integration of the Dynamic LINQ library. While the -Criteria approach is limited to string values, the -Where filtering allows you to use proper objects. Because this capability is only available starting with Sitecore 7.5 – if you attempt to use the -Where parameter on an older version – the cmdlet will fail to yield any results and you will see an appropriate warning message instead.

Let’s examine how you would do similar searches using both parameter sets. Let’s find all Template fields defined in English. For the sake of time saving let’s return only first 10 items in both cases.

Dynamic Linq

Find-Item `
    -Index sitecore_master_index `
    -Where 'TemplateName = @0 And Language=@1' `
    -WhereValues "Template Field", "en" `
 -First 10

Criteria search

Find-Item `
    -Index sitecore_master_index `
    -Criteria @{Filter = "Equals"; Field = "_templatename"; Value = "Template Field"; CaseSensitive = $true},
    @{Filter = "Equals"; Field = "_language"; Value = "en"; CaseSensitive = $true} `
    -First 10

As you can see the -Where approach is much simpler to understand, and while we don’t use it here – the -WhereValues can be proper objects like dates. This enables you to search for items that are e.g. older than a week.

But I’m not getting items from the cmdlet!

Straight from the commandlet you’re getting the Sitecore.ContentSearch.SearchTypes.SearchResultItem objects rather than full blown Sitecore Items. It’s done this way so you can do lightweight searching and filtering and only convert the final results to items. If you recall we’ve always had a Wrap-Item commandlet that has recently been renamed to Initialize-Item (old name still available as an alias). This commandlet has been extended to support SearchResultItem as an input from the pipeline. Consequently you can do the following with the above search to get the proper Items you can work with:

Find-Item `
    -Index sitecore_master_index `
    -Where 'TemplateName = @0 And Language=@1' `
    -WhereValues "Template Field", "en" `
    -First 10 |
    Initialize-Item

You can find some speed measurements using different approaches to get items running the script in this gist.

How do I find what I can filter my items against.

If you’re stuck on a Sitecore version older than 7.5 you might find the following query helpful to find the Index keys by which you can filter:

Find-Item -Index sitecore_master_index `
          -Criteria @{Filter = "StartsWith"; Field = "_fullpath"; Value = "/sitecore/system/modules/PowerShell/" } `
          -First 1 | 
    Select -expand "Fields"

(No Ratings Yet)

Loading...

This entry (Permalink) was posted on Tuesday, April 7th, 2015 at 10:06 am and is filed under PowerShell, Sitecore, Software, Software Development, Solution, Web applications. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response , or trackback from your own site.