The API

You can use dtSearch from any .NET language, Java or C++. In this case I'm going to use the .NET API and C# 4.0, but the ideas are more or less the same in any language because the same classes are provided to do the same job. You could say that only the language changes the classes are largely unaltered.

Start a new C# Windows forms project and add a reference to:

dtSearchNetApi4.dll

which you will generally find in

C:\Program Files\dtSearch Developer\bin

or

C:\Program Files (x86)\dtSearch Developer\bin

(there are versions for earlier .NET assemblies but in most cases version 4 is what you should be using).

Also add:

using dtSearch.Engine;

to save having to type out fully qualified names.

Now get started all you really need to know is the key class that does most of the work related to search is SearchJob. Whenever you are trying to get to grips with a new API finding the class (or small number of classes) where it all starts is usually the way to get on top of it fast. In this case once you know that SearchJob is what you need to set up a search of an index it is all remarkably easy.

Place a button on the form and in its click event handler we first create an instance of SearchJob:

SearchJob SJob1 = new SearchJob();

Before we can perform the search we need to setup some details. First we need to specify the location fo the index:

SJob1.IndexesToSearch.Add(@"C:\Users\
     ian\AppData\Local\dtSearch\test");

Of course you have to replace the string with the full path to the index you are using. Notice that you can specify multiple indexes because the property is a collection.

Next we need to specify what we are searching for. This can be done in two ways. Using the Request property to specify search terms or using the BooleanConditions property to specify a logical expression involving search terms. For example:

SJob1.BooleanConditions = "Hello and World";

will search for documents containing "Hello" and "World" in the index and

SJob1.BooleanConditions = "Hello or World";

will search for documents containing "Hello" or "World" in the index. Following this there are a range of optional parameters you can set. For example:

SJob1.MaxFilesToRetrieve = 10;

You can set all of the more sophisticated search options at this point - filters, stemming, fuzzy search, exclusions etc.

Now we are already to perform the search. You can do it as a blocking call or you can use an event to work asynchronously. The simplest option is to use a blocking call:

SJob1.Execute();

but note that once you call this method your entire application is frozen until the search is complete or an error occurs. This isn't too bad with a small index but of course it quickly becomes unacceptable. As well as using an event to process the data asynchronously you could also use a worker thread to run the search - again not difficult but not specific to using dtSearch.

When the call to Execute complete  the SearchJob instance has properties which return the results of the search. For example, the HitCount property gives an integer that holds the number of hits the search returned. For example:

MessageBox.Show( SJob1.HitCount.ToString());

More importantly SearchJob returns a SearchResults object via its Results property. This provides a collection of documents that the search found. To make use of this collection you have to make use of the GetNthDoc method to make the nth document the current document and then you can use various properties to return its details. For example:

SearchResults results = SJob1.Results;
for (int i = 0; i < results.Count; ++i)
{
 results.GetNthDoc(i);
 listBox1.Items.Add(results.DocName);
}
 

Which simply adds the document names to a ListBox placed on the form.

Yes it really is this easy.

Of course I've left out the usual error handling to make it easier to follow but this isn't difficult to add - there is an Error property that you can test. It also doesn't take into account that the results object could be very large indeed. In this case garbage collection might be a problem so you should use the "using" construct to ensure the the results object is disposed of when you are finished with it. Again not difficult.

What next?

The next step in most uses of an index search is converting the results to something more suitable. See the FileConverter Class for an easy way to convert to HTML, RTF or text.  You can also export the results as XML.  If you also want to control the construction and maintenance of the index itself then you need to look up the IndexJob object which is very similar to the SearchJob object.

Building an application around dtSearch is more a matter of what you do with the search results and in many cases how you allow the search to be specified by the user.

Then there are many other features that we haven't even mentioned - CDsearch, Websearch and setting up the web Spider to name just three, but these are other stories.

To try dtSearch for yourself download the 30-day evaluation from dtsearch.com.