Monitoring IndexJobs in .NET

How to monitor the progress of an index update in .NET

Remarks

There are two ways to monitor the progress of an IndexJob in the .NET API:

(1) If the IndexJob was started with ExecuteInThread, you can call IsThreadDone to determine whether the job is done and to obtain an IndexProgressInfo with details on the current state of the indexer.

(2) You can attach an object derived from IIndexStatusHandler to the IndexJob to receive notifications as the job progresses through the OnProgressUpdate function.

IsThreadDone

Calling IsThreadDone is generally best for updating user interface elements such as dialog boxes. Typically the application would call ExecuteInThread when the update starts and then have a timer in a status dialog box to trigger calls to IsThreadDone() to update a progress bar. If the application provides a cancel button, AbortThread() can be called when the user clicks Cancel to cancel the IndexJob. (A thread may still require a brief amount of time to stop the indexer and close the index, so the calling application should wait for IsThreadDone to return true before assuming that it is safe to exit.)

IIndexStatusHandler

IIndexStatusHandler is best for situations where it is important to have complete information, such as logging the names of documents indexed and how each file was indexed. Each time IIndexStatusHandler.OnProgressUpdate is called, the IndexProgressInfo.UpdateType will indicate the reason for the notification. The UpdateType is a MessageCode value that indicates when, for example, a file was successfully indexed (dtsnIndexFileDone) or could not be indexed due to an error (dtsnIndexFileOpenFail, dtsnIndexFileEncrypted). Example:

public class MyIndexer : dtSearch.Engine.IIndexStatusHandler {
    // The indexer will halt if CheckForAbort does not return AbortValue.Continue.
    public AbortValue CheckForAbort() {
        return AbortValue.Continue;
        }

    // The indexer will call OnProgressUpdate with many different types of notifications as the
    // update proceeds.
    public void OnProgressUpdate(dtSearch.Engine.IndexProgressInfo info) {
        if (info.UpdateType == MessageCode.dtsnIndexFileDone)
            Console.WriteLine("Indexed: " + info.File.Name);
        else if (info.UpdateType == MessageCode.dtsnIndexFileOpenFail)
            Console.WriteLine("Not Indexed: " + info.File.Name + " " + info.File.OpenFailMessage);
        else if (info.UpdateType == MessageCode.dtsnIndexFileEncrypted)
            Console.WriteLine("Encrypted: " + info.File.Name);
        }

    // Start an index update and use this object to receive progress notifications.
    public void DoIndex() {
        IndexJob ij = new IndexJob();
        ...
        ij.StatusHandler = this;
        ...
        ij.Execute();
        }
};

To cancel an index update using IIndexStatusHandler, return AbortValue.Cancel or AbortValue.CancelImmediately from your CheckForAbort function. AbortValue.Cancel causes the update to stop after the current file and to commit data indexed so far. AbortValue.CancelImmediately cancels the update immediately, without saving any changes to the index (so the index will revert to its state as of the last commit).

Group

Monitoring Index Jobs