Revit API 2012: External DB Application (IExternalDBApplication)

Revit API 2012 provides one more application type, IExternalDBApplication, which is supposed to help do some DB stuffs at Revit startup. In this post, we will focus on the new DB external application.

Its appearance and usage is pretty much the same as the external application, IExternalDBApplication. It also has the OnStartup and OnShutdown methods for us to override. Of course, their arguments and return values are different, one is UI related and the other is DB related.

Here is a sample implementation:

#region Namespaces

using System;
using System.Text;
using System.Linq;
using System.Xml;
using System.Reflection;
using System.ComponentModel;
using System.Collections;
using System.Collections.Generic;
using System.Windows;
using System.Windows.Media.Imaging;
using System.Windows.Forms;
using System.IO;

using Autodesk.Revit.ApplicationServices;
using Autodesk.Revit.Attributes;

using Autodesk.Revit.DB;
using Autodesk.Revit.DB.Events;
using Autodesk.Revit.DB.Architecture;
using Autodesk.Revit.DB.Structure;
using Autodesk.Revit.DB.Mechanical;
using Autodesk.Revit.DB.Electrical;
using Autodesk.Revit.DB.Plumbing;

using Autodesk.Revit.UI;
using Autodesk.Revit.UI.Selection;
using Autodesk.Revit.UI.Events;

using Autodesk.Revit.Collections;
using Autodesk.Revit.Exceptions;
using Autodesk.Revit.Utility;

using RvtApplication = Autodesk.Revit.ApplicationServices.Application;
using RvtDocument = Autodesk.Revit.DB.Document;

#endregion

namespace RevitAddinCS1
{
    [Transaction(TransactionMode.Manual)]
    [Regeneration(RegenerationOption.Manual)]
    public class ExtDbApp : IExternalDBApplication
    {
        #region Cached Variables

        public static ControlledApplication _cachedCtrlApp;
        
        #endregion

        #region IExternalApplication Members

        public ExternalDBApplicationResult OnStartup(ControlledApplication ctrlApp)
        {
            try
            {
                _cachedCtrlApp = ctrlApp;

                //TODO: add you code below.
                MessageBox.Show("ExtDbApp");

                return ExternalDBApplicationResult.Succeeded;
            }
            catch (Exception ex)
            {
                MessageBox.Show( ex.ToString() );
                return ExternalDBApplicationResult.Failed;
            }
        }

        public ExternalDBApplicationResult OnShutdown(ControlledApplication ctlApp)
        {
            try
            {

                return ExternalDBApplicationResult.Succeeded;
            }
            catch (Exception ex)
            {
                MessageBox.Show(ex.ToString());
                return ExternalDBApplicationResult.Failed;
            }
        }

        #endregion       
    }
}

Here is the manifest file for the DBApplication:

<?xml version="1.0" encoding="utf-8"?>
<RevitAddIns>
  <AddIn Type="DBApplication">
    <Assembly>C:\Temp\RevitAddinCS1\bin\Debug\RevitAddinCS1.dll</Assembly>
    <FullClassName>RevitAddinCS1.ExtDbApp</FullClassName>
    <ClientId>4422d57c-7fd6-45e0-a4ba-e00180DB2012</ClientId>
    <Name>RevitAddinCS1 ExtDbApp</Name>
    <VendorId>RAW</VendorId>
  </AddIn>
</RevitAddIns>

As can be seen, the manifest file for the DBApplication type is also the same as for the Application type except for the AddIn type. The VendorId cannot be skipped, otherwise the famous No VendorId Node error message would show up. Though the obsolete AddinId node can still be used as documented, its replacement, ClientId, had better be used.

After the application is compiled, the manifest file properly deployed, and the Revit 2012 starts up, we will see the introduction message from the Startup method of the IExternalDBApplication implementation.

Revit Addin Wizard (RevitAddinWizard) is going to provide an External DB Application wizard to help implement the IExternalDBApplication interface automatically and reliably.