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
