Revit API 101.1

This is yet another installment of the ongoing Revit API 101 installment that can be viewed in numeric order from 101.#. Each are free so long as you agree to buy the writer a beer when you next see him: @AYBABTM (Austin, TX or next conference/gathering). While some basic understanding of .NET terminology and understanding is assumed in these posts, you'll do just fine if you follow the images and explanations.

I'll attempt to keep the posts slim and to the point, so if you have questions, please post them in the comments. Just remember, there's no crying in .NET.

The Revit API Namespaces

There are two DLL references that make up the entire Revit API, only one of which is required for all Revit API projects.

• RevitAPI.dll                     (required for all Revit API projects)
• RevitAPIUI.dll                 (required to access the application user interface objects)

The Required Transaction Attribute for All Revit API Class Implementations

There is now only one required API attribute implementation required for all Revit API implementations. The TransactionMode attribute needs to always be set immediately above the main class declaration as shown below. The TransactionMode attribute informs the Revit API as to how the pass or fail is handled for any given attempt to make changes to a Revit document using the Revit API. There are three settings for the TransactionMode attribute. The Automatic option is soon to be Obsolete, so that really only leaves two valid settings to chose from. The read-only setting is just that, so if you need to make changes to a model document, you should set your transaction attribute to Manual. We'll get into how to build and manage transactions in a future post.

The Revit API Implementations (3)

There are three ways to gain access to the .NET Revit API customization environment. The IExternalcommand implementation is by far the most common and will be discussed in our first real code example. The IExternalApplication interface is the second type and is used either to gain access to the IExternalCommand functions or events (document or application). The third and less common implementation is the IExternalDBApplication implementation which is similar to the IExternalCommand interface except that it cannot access any of the RevitAPIUI.dll namespaces.

The sample API Templates demonstrate implementations of the IExternalCommand interface in the Command class as well as the IExternalApplication interface in the Application class. The IExternalDBApplication class is similar to the IExternalApplication class except for minor differences as shown below.

Sample IExternalCommand Interface

Imports Autodesk.Revit.ApplicationServices
Imports Autodesk.Revit.Attributes
Imports Autodesk.Revit.DB
Imports Autodesk.Revit.UI
Imports Autodesk.Revit.UI.Selection

''' <summary>
''' Revit 2013 Command Class 
''' </summary>
''' <remarks></remarks>
<Transaction(TransactionMode.Manual)>
Public Class Command

    Implements IExternalCommand

    ''' <summary>
    ''' Command Entry Point
    ''' </summary>
    ''' <param name="commandData">Input argument providing access to the Revit application and documents</param>
    ''' <param name="message">Return message to the user in case of error or cancel</param>
    ''' <param name="elements">Access elements</param>
    ''' <returns>Cancelled, Failed or Succeeded</returns>
    Public Function Execute(ByVal commandData As ExternalCommandData,
                            ByRef message As String,
                            ByVal elements As ElementSet) As Result Implements IExternalCommand.Execute
        Try
            ' Add Your Code Here

            ' Return Success
            Return Result.Succeeded

        Catch ex As Exception

            ' Failure Message
            message = ex.Message
            Return Result.Failed

        End Try

    End Function
End Class

Sample IExternalApplication Interface

Imports Autodesk.Revit.ApplicationServices
Imports Autodesk.Revit.Attributes
Imports Autodesk.Revit.DB
Imports Autodesk.Revit.UI
Imports Autodesk.Revit.UI.Selection

''' <summary>
''' Revit 2013 API Application Class
''' </summary>
''' <remarks></remarks>
<Transaction(TransactionMode.Manual)> 
Class Application

    Implements IExternalApplication

    ''' <summary>
    ''' Fires off when Revit Session Starts
    ''' </summary>
    ''' <param name="application">The UI controlled application</param>
    ''' <returns>Returned status</returns>
    Public Function OnStartup(ByVal application As UIControlledApplication) _
            As Result Implements IExternalApplication.OnStartup

        Try

            ' Add your code here

            ' Return Success
            Return Result.Succeeded

        Catch ex As Exception

            ' Return Failure
            Return Result.Failed

        End Try

    End Function

    ''' <summary>
    ''' Fires off when Revit Session Ends
    ''' </summary>
    ''' <param name="application">The UI controlled application.</param>
    ''' <returns>Returned status</returns>
    Public Function OnShutdown(ByVal application As UIControlledApplication) _
            As Result Implements IExternalApplication.OnShutdown

        ' Return Success
        Return Result.Succeeded

    End Function

End Class

Sample IExternalDBApplication Interface

Imports Autodesk.Revit.ApplicationServices
Imports Autodesk.Revit.Attributes
Imports Autodesk.Revit.DB
Imports Autodesk.Revit.UI
Imports Autodesk.Revit.UI.Selection

''' <summary>
''' Revit 2013 API DBApplication Class
''' </summary>
''' <remarks></remarks>
<Transaction(TransactionMode.Manual)>
Public Class DBApplication

    Implements IExternalDBApplication

    ''' <summary>
    ''' DB Application Shutdown
    ''' </summary>
    ''' <param name="application">The controlled application</param>
    ''' <returns>Returned status</returns>
    ''' <remarks></remarks>
    Public Function OnShutdown(application As ControlledApplication) _
            As ExternalDBApplicationResult Implements IExternalDBApplication.OnShutdown

        ' Return Success
        Return Result.Succeeded

    End Function

    ''' <summary>
    ''' DB Application Startup
    ''' </summary>
    ''' <param name="application">The controlled application</param>
    ''' <returns>Returned status</returns>
    ''' <remarks></remarks>
    Public Function OnStartup(application As ControlledApplication) _
            As ExternalDBApplicationResult Implements IExternalDBApplication.OnStartup

        Try

            ' Add your code here

            ' Return Success
            Return Result.Succeeded

        Catch ex As Exception

            ' Return Failure
            Return Result.Failed

        End Try

    End Function

End Class