Model Checker API

Getting started

The Model Checker API is designed to provide a simple system for automating the tasks that the full UI version of Model Checker does. You can read and set checksets, local configurations, run checks, and get and save reports. First, here is some terminology that you will need to know.

Model Checker uses checkset files to store all of the data need to run a set of checks and generate reports, including the tree structure of the file (sections and headings). These files are saved in XML format and can be created and modified using the configurator tool. Each Revit model can have a single path to a checkset file stored in its extensible storage. The Model Checker API has a ‘CheckSet’ class that represents a single checkset.

Model Checker must also save model specific preferences (such as what items are checked and unchecked, user specific filter values, etc.) without writing to the source xml file as this would be problematic, especially for checksets in the public library. To do this, model checker uses ‘RunState’ objects to store and retrieve the model specific settings for a checkset.

When running checks, the object that will be returned is a ‘ReportRun’ object. This object represents a single run of reports that were done and can contain reports for one or more models. The ReportRun has a property that holds a collection of ‘FileReport’ objects; each of these represents all checks that were run on a single Revit file and, possibly, its links.

With that basic understanding, the following sections contain specifics of how to automate this process.

Project setup

To reference the Model Checker API you will simply need to reference 2 DLL files in your project:

1. AIT.ModelChecker.API.dll – This contains the core data model and classes that do not require Revit interaction directly. The base namespace is ADSK.AIT.ModelChecker.API and under that you will find the basic data model and most service classes.
2. AIT.ModelChecker.RevitAPI.dll – This contains all API classes that require direct Revit access. You will need to reference the version built to the Revit version you wish to target.

Configuration

Setting the Checkset Path

If you wish to set the path to the checkset file you may do so by creating a ‘CheckSetLocationRepository’ for the document and then storing the path. The code for this would look as follows:

    var locationRepository = new CheckSetLocationRepository(doc);
    locationRepository.SaveCheckSetLocation("http://mycompany.com/checksets/someCheckset.xml");

Getting a Checkset

In order to run a check, you will need a checkset object which you can load from a disk or web-based path. To obtain the CheckSet object create a ‘CheckSetService’ instance and call ‘GetCheckSet’, passing in the path of the checkset you wish to load. This will return the checkset object.

If you know the path of the checkset you wish to load you may simply load it this way. If you would like to obtain the location of the checkset stored in the model you may do so by constructing an instance of ‘CheckSetLocationRepository’ using the document you wish to study and a prebuilt options service (which can simply be constructed with the default constructor). You can then call ‘GetCurrentCheckSetLocation()’ to obtain the current stored location. Keep in mind that this may be null or empty if a path has not been saved in the model.

An example of getting the checkset location from the model and retrieving the checkset object may look as follows:

    CheckSet GetCurrentCheckSet(Document doc)
    {
        var locationRepository = new CheckSetLocationRepository(doc);
        var checkSetPath = locationRepository.GetCurrentCheckSetLocation();

        if (string.IsNullOrEmpty(checkSetPath)) return null;

        var preBuiltOptionsService = new PreBuiltOptionsService();
        var service = new CheckSetService(preBuiltOptionsService);
        return service.GetCheckSet(checkSetPath);
    }

If you wish to run the checkset in its default state this is sufficient. However, as mentioned, Model Checker is also able to save a local ‘RunState’ object to the model which stores the users settings for this model. In order to update the checkset to reflect this information you will need to obtain the run state object and set the configuration. To obtain the run state construct a ‘RunStateRepository’ for the document you are working with and call ‘GetRunState()’. This will give you the run state object (keeping in mind that it can be null if no run state is stored). You can then use the static ‘Utility’ class to set the checkset values based on the run state. With the update, the above code snippet would look as follows:

    CheckSet GetCurrentCheckSet(Document doc)
    {
        var locationRepository = new CheckSetLocationRepository(doc);
        var checkSetPath = locationRepository.GetCurrentCheckSetLocation();

        if (string.IsNullOrEmpty(checkSetPath)) return null;

        var preBuiltOptionsService = new PreBuiltOptionsService();
        var service = new CheckSetService(preBuiltOptionsService);
        var checkSet = service.GetCheckSet(checkSetPath);

        var runStateRepository = new RunStateRepository(doc);
        var runState = runStateRepository.GetRunState();

        if (runState != null)
        {
            Utility.SetCheckSetFromRunState(checkSet, runState);
        }

        return checkSet;
    }

You now have a checkset object ready to proceed with checks.

Running Checks

Once you have a checkset object, you are ready to run checks. Running checks can be done in one of two ways, model by model, or in batch. For either of these, you will need an implementation of the IRevitIniService interface. You can find one of these constructed for you by referencing the AIT.Common.API.dll file and then constructing the default implementation with an instance of the default IIniService implementation there. However, this service simply provides the collaboration cache path, so you can also create your own simple implementation of the interface that simply gives the known collaboration cache path. The simplest implementation of this interface may look as follows:

    public class RevitIniService : IRevitIniService
    {
        public string GetCollaborationCachePath() =>
            @"C:\some\known\collaboration\cache\path";
    }

Batch Checks

The primary method for running check is the batch check runner. This takes a simple set of inputs and returns you a result object for the entire run as well as a list of errors encountered (if any). To run a batch check construct a ‘BatchCheckRunner’ object; you will need to pass in the Revit application object and an ini service. Second, create a collection of ‘FileCheckSetting’ objects; these are a simple structure that stores the file path and a Boolean value indicating if linked models should be checked as well. Then simply call the ‘RunChecks’ method on the check runner.

If you wish you can also subscribe to the ‘ProgressChanged’ event to be notified of progress updates in the run. Running checks would look as follows:

    ReportRun RunChecksAndGetReport(CheckSet checkSet, Application revitApp)
    {
       var iniService = new RevitIniService(new IniService(), 2025);
        var checkRunner = new BatchCheckRunner(revitApp, iniService);

        var files = new List<FileCheckSetting>()
        {
            new FileCheckSetting(@"C:\Some\Path\Checksets.xml") {CheckLinks = false}
        };

        checkRunner.ProgressChanged += progressData =>
        {
            // Do something to report progress
        };

        var run = checkRunner.RunChecks(files, checkSet, out var errors);

        if (errors.Any())
        {
            // Do some error handling
        }

        return run;
    }

Document Checks

Alternately, you may run individual document checks yourself. This requires that you open the models yourself but may afford slightly more control over the check runs. To do a document check construct a ‘DocumentCheckRunner’ object with the document you wish to check and an ini service. Then call ‘RunChecks’ with the proper arguments. Note that there are some option arguments on this method that allow you to add the document check you are running to an existing ReportRun object. Running a document check would look as follows:

    ReportRun RunChecksAndGetReport(CheckSet checkSet, Document doc)
    {
       var iniService = new RevitIniService(new IniService(), 2025);
        var checkRunner = new DocumentCheckRunner(doc, iniService);

        checkRunner.ProgressChanged += progressData =>
        {
            // Do something to report progress
        };

        var run = checkRunner.RunChecks(false, checkSet);

        return run;
    }

Saving and Exporting Results

Once you have run a check and have a ReportRun object you need to save that data in some way. You can do any or all of the following three things with this object:

1. Save it to the model - This will save the report data in the model’s extensible storage and it will be available to the user as their last run report. Saving this does not require a transaction as Model Checker will create its own transaction. However, you will need to save the model before closing it or this data will not be saved. This is done through the ‘ReportRunRepository’ object; code for this option is as follows:

    void SaveRunResult(ReportRun result, Document doc)
    {
            var preBuiltOptionsService = new PreBuiltOptionsService();
        var checkSetService = new CheckSetService(preBuiltOptionsService);
        var repository = new ReportRunRepository(doc, checkSetService);
   
        repository.SaveRun(result);
    }

2. Export to HTML - Results can be exported to an HTML file for archiving or analysis. To do so construct an ‘ResultExporterHtml’ object and export with the required options. Code for this option is as follows:

    void ExportRunResult(ReportRun result)
    {
        var exporter = new ResultExporterHtml();
        var options = new ExportOptions()
        {
            ExportLocation = @"C:\Some\Export\Folder", 
            ExportLists = true
        };
        exporter.ExportReport(result, options);
    }

3. Export to Excel - Similar to HTML, results can be exported to Excel using the ‘ResultExporterExcel’ class. Code for this is as follows:

    void ExportRunResult(ReportRun result)
    {
        var exporter = new ResultExporterExcel();
        var options = new ExportOptions()
        {
            ExportLocation = @"C:\Some\Export\Folder",
            ExportLists = true
        };
        exporter.ExportReport(result, options);
    }