EPiServer  /  Find April 16, 2013

EPiServer Find 101

New to EPIServer Find and want a jump start? Here's what you need to know.

If you're new to EPiServer Find and going to use it in a project, or just want to try it out, there's plenty of documentation on Find's site. There's also training offered by EPiServer. Not to mention the forum on EPiServer World.

Sometimes you need a little quick start though. Here's the most essential things to know about Find's .NET API and CMS integration.

Setting up

You can grab yourself a free test index at find.episerver.com. Once you have created your index you can copy and paste the necessary configuration into your app.config or web.config.

Finally you need to download and reference Find's .NET API. That's easily done through NuGet given that you have EPiServer's NuGet feed added as a package source. There's three packages to choose from. For an EPiServer CMS site install EPiServer Find CMS Integration. For any other type of .NET application install EPiServer Find Client API.

Communicating with the REST API

You can use the .NET API from any .NET application. When doing so, all communication with Find's REST API goes through an instance of the IClient interface. To obtain such an instance when not using the CMS integration you can use the Client.CreateFromConfig() method to create it based on settings in app.config/web.config.

If you're using the CMS integration or any other integration for other EPiServer products always use the singleton SearchClient.Instance. This is important. The singleton is preconfigured with conventions set up for CMS content.

"If you're using the CMS integration always use the singleton SearchClient.Instance"

Finding things

Once you have a client search for indexed objects (CMS objects are automatically indexed upon save) using the Search<T>() method where T is the type of objects you want to search for. The method supports inheritance and searching for objects that implement an interface.

The Search method returns an object which you can add queries and filters to. Use the For method for free text search. Use the Filter method to apply criterias.

The Filter method is very similar to LINQ's Where method but has a slightly different syntax. You can filter on any property of a "simple" type, such as int, string, DateTime, double, GUID etc. Check out the documentation for more information or use Intellisense.

You can use methods with familiar names from LINQ to apply sorting, projections and paging - OrderBy, SelectSkip, Take etc.

Once you're done building your search request execute it against the REST API and get the result using the GetResult() method. The returned object will be an object the implements IEnumerable<T> so you can start iterating over the results straight away.

Note that if you're searching for CMS objects such as PageData and want to fetch the full objects you shouldn't use GetResult but instead use the GetContentResult() method. When using the integration for CMS 6, that's called GetPagesResult.

"if you're searching for CMS objects such as PageData and want to fetch the full objects ... use the GetContentResult() method"

Unified Search

One of the things that makes Find powerful and easy to use at the same time is the fact that it let's us index our own .NET object and search for them in a strongly typed way. Sometimes though, such as building a search page, we want to search over many different types. Find makes that easy to using a concept called Unified Search.

In general - use the regular Search method for building listings, navigations and specialized search page with ease and use Unified Search when building free text search pages where users should search in *everything*.

Where to go from here

That's it. A few key concepts to get you started and a few important things to remember to avoid being faced by a YSOD.

Once you've familiarized yourself with Find's .NET API you can move on to indexing custom objects or why not check out some of the more specialized and interesting methods such as MoreLike and BoostMatching. Also, don't miss out of the many types of facets which you can use to build many interesting things.

Want to build a search page for an EPiServer site quickly? Here's one complete with annotated source code for you.

Happy Finding!

PS. For updates about new posts, sites I find useful and the occasional rant you can follow me on Twitter. You are also most welcome to subscribe to the RSS-feed.

Joel Abrahamsson

Joel Abrahamsson

I'm a passionate web developer and systems architect living in Stockholm, Sweden. I work as CTO for a large media site and enjoy developing with all technologies, especially .NET, Node.js, and ElasticSearch. Read more


comments powered by Disqus

My book

Want a structured way to learn EPiServer 7 development? Check out my book on Leanpub!

More about EPiServer Find