External commands are accessible from the Add-ins tab under the External Tools drop-down button. External commands have access to the current document as well as any elements selected when the command is executed. Commands can be registered into Revit through the Revit.ini file or by using an .addin manifest file new to the Revit 2011 API. This new feature will be explained in greater detail later in this chapter in the section "External Utility Registration Options."

The memory lifetime for external commands lasts only from the time the command is clicked, to when the command returns success or failure. Any objects created or held in memory by the command are destroyed when the command is completed. Data will not persist in memory alone from one external command to another. If data persistence is needed from one external command to another, you will need to employ a means to store this data either by parameters or by an external database.

Imports Autodesk.Revit
Imports Autodesk.Revit.Attributes
Imports Autodesk.Revit.DB
Imports Autodesk.Revit.UI

<Regeneration(RegenerationOption.Manual)> _
<Transaction(TransactionMode.Automatic)> _
Public Class Command
    Implements IExternalCommand
    Public Function Execute(ByVal commandData As UI.ExternalCommandData, _
                ByRef message As String, _
                ByVal elements As DB.ElementSet) _
                As UI.Result Implements IExternalCommand.Execute
        Try
            ' Command implementation
            Return Autodesk.Revit.UI.Result.Succeeded

Catch ex As Exception
         Return Autodesk.Revit.UI.Result.Failed
      End Try
   End Function
End Class

using Autodesk.Revit;
using Autodesk.Revit.Attributes;
using Autodesk.Revit.DB;
using Autodesk.Revit.UI;

[Regeneration(RegenerationOption.Manual)]
[Transaction(TransactionMode.Automatic)]
public class Command : IExternalCommand
{    public Autodesk.Revit.IExternalCommand.Result
Execute(Autodesk.Revit.ExternalCommandData commandData,
        ref string message, Autodesk.Revit.ElementSet elements)
    {
        // Command implementation
    }
}

Public Function Execute(ByVal commandData As ExternalCommandData, _
                        ByRef message As String, _
                        ByVal elements As DB.ElementSet) _
                        As Result Implements IExternalCommand.Execute
    Try
        ' Functionality extends from here
        Return Result.Succeeded
    Catch ex As Exception
        ' If something goes wrong, exit and return failed
        Return Result.Failed
    End Try
End Function

Return IExternalCommand.Result.Succeeded
Return IExternalCommand.Result.Failed
Return IExternalCommand.Result.Canceled

External applications are loaded when Revit starts and remain loaded until Revit shuts down. One of the biggest advantages that applications have over commands is that applications provide access to Revit document events. Applications are typically accessible from the Add-Ins tab of the ribbon, but the 2011 API now also provides a means to add application ribbon items to the Analyze tab in Revit MEP 2011.

Imports Autodesk.Revit.UI
Imports Autodesk.Revit.UI.Events
Imports Autodesk.Revit.Attributes

<Transaction(TransactionMode.Automatic)> _
<Regeneration(RegenerationOption.Manual)> _
Public Class App
     ' Required Interface...

Implements IExternalApplication
       Public Function OnStartup(ByVal a As UIControlledApplication) _
       As Result Implements IExternalApplication.OnStartup
               ' OnStartup implementation
       End Function

       Public Function OnShutdown(ByVal a As UIControlledApplication) _
           As Result Implements IExternalApplication.OnShutdown
               ' OnShutdown implementation
       End Function

End Class

using Autodesk.Revit.UI;
using Autodesk.Revit.UI.Events;
using Autodesk.Revit.Attributes;

namespace ClassLibrary1
{
     [Regeneration(RegenerationOption.Automatic)]
     public class Application : IExternalApplication
     {
         Public Result OnStartup(ControlledApplication application)
         {
             // OnStartup implementation
     }
     Public Result OnShutdown(ControlledApplication application)
     {
         // OnShutdown implementation
     }
  }
}

There are now two options for registering external commands and applications into the Autodesk Revit user interface.

<?xml version="1.0" encoding="utf-8" standalone="no" ?>
<RevitAddIns>
 <AddIn Type="Command">
  <Assembly>C:Revit ProjectsExampleCommand.dll</Assembly>
  <AddInId>72d6cd76-5462-4c97-b56c-5468b08ba742</AddInId>
  <FullClassName>ExampleCommand.Command</FullClassName>
  <Text>Batch Family Export Utility</Text>
  <VisibilityMode>NotVisibleInFamily</VisibilityMode>
  <LongDescription>Batch export all family files as external RFA files. i
  Each file will be saved into a subdirectory named by its category i
  beneath the parent directory selected by the user.</LongDescription>
  <TooltipImage> C:Revit ProjectsPreview_BatchFamilyExport.PNG</TooltipImage>
 </AddIn>
</RevitAddIns>

<?xml version="1.0" encoding="utf-8" standalone="no" ?>
<RevitAddIns>
 <AddIn Type="Application">
  <Name>ExampleApplication</Name>
  <Assembly>c:Revit Projects ExampleApplication.dll</Assembly>
  <AddInId>fb36c4b0-d4c2-4ead-96db-81f48407e57a</AddInId>
  <FullClassName>ExampleApplication.Application</FullClassName>
 </AddIn>
</RevitAddIns>

[ExternalCommands]
ECCount=1

ECName1=Batch Family Export
ECClassName1=BatchFamilyExporter.Command
ECAssembly1=C:BatchFamilyExtractorinDebugBatchFamilyExporter.dll
ECDescription1=Batch Family Export Utility...

Several development environment options are available for building and debugging .NET Revit API utilities. Although Visual Studio 2008 Professional is preferred, it is not free. Microsoft provides free express versions of Visual Studio 2008 in both VB.NET and C# on its website at www.microsoft.com/express. These express versions provide more than enough functionality to generate a fully featured .NET Revit API utility.

A new .NET programming language known as F# is quickly emerging as the next generation of .NET technology. F# has been so successful that Microsoft has promoted it to a "first-class" language in Visual Studio 2010. See www.fsharp.net for more information.

Visual Studio Debug Settings

Debugging a Revit command or application in Visual Studio 2008 requires that you first enter the full path and filename to your Revit.exe in the Start External Program field in the Debug tab of the Project Properties dialog box, as shown in Figure 24.1. The Revit API does not yet provide a means to interact with the Revit application in an externally defined stand-alone executable file. Entering the full path and filename to a Revit file in the Command Line Arguments field will launch that file when the project enters debug mode.

Debugging on a 64-Bit Operating System

You will not be able to edit your code in break mode on a 64-bit operating system in Visual Studio 2008. Use a 32-bit operating system as your development station as a workaround.

Figure 24.1. Setting debug options in Visual Studio

The Revit 2011 SDK is available on the Revit 2011 installation disk and in the downloadable installation package; however, you can download the latest version of the SDK from Autodesk's website at www.autodesk.com/revit. The SDK contains several working samples of code written in both the C# language as well as VB.NET. Examples range from simple element modifications to family creation. The "Getting Started with the Revit API" document included with the SDK will help you with the examples provided.

The Revit 2011 API requires the .NET Framework Version 3.5 as a prerequisite, but since this same framework version is required to install and run Revit in general, it is not necessary to build your applications with this as a runtime prerequisite. If you choose to build your application using a .NET Framework version newer than 3.5, you should build your application to verify the installation of your required framework version at runtime.

There was just one lonely DLL in previous releases of the API representing the entire thing. There are now two DLLs, each with its own scope, in the Autodesk Revit API:

Access to the document- and application-level interfaces through both the RevitAPIUI.dll and the RevitAPI.dll is now provided through a split of the Document and Application classes.

Transactions are a means to prevent corruption by only allowing changes to be made when all required methods and conditions succeed. "All or nothing" is a good way to describe a transaction. Transactions roll back any changes contained within the transaction when a requirement or method does not return successfully. Transactions are common in complex database programs and are critical for ensuring that a complex operation succeeds as intended.

The 2011 API now provides a much more comprehensive system for handling transactions for changes being made to the model. There are three main transaction classes included in the Revit 2011 API. The most notable is the ability to manage subtransactions. Each of the three transaction types listed here share these four common methods:

The Commit and RollBack methods also return a status indicating whether or not the method was successful. Available status values for Commit and RollBack include the following:

In the methods mentioned here for Commit and RollBack, the Pending method is set after an attempt to either submit or roll back a transaction object but because of failures, that process could not be completed yet and is waiting for the end user's response (in a modeless dialog). Once the failure processing is finished, the status will be automatically updated (to either Committed or RolledBack status).

In the Revit 2011 API, events no longer automatically open transactions. Because of this change, the document won't be modified during an event unless one of the event's handlers modifies it by making changes within a transaction. If your application requires changes to anything in the document, these transactions are no longer optional.

To help improve the speed of a custom application or command as it interacts with the elements in a project, new regeneration options are available within the Revit API. In previous versions, all actions on model elements would force the model to update or regenerate automatically. Within the 2011 API, you can now specify automatic or manual regeneration. There is no default for this option and you must apply it to legacy application classes to allow your application to function in Revit 2011.

The new Autodesk.Revit.Attributes.RegenerationAttribute custom attribute should be applied to your implementation class of the IExternalCommand interface and IExternalApplication interface to control the regeneration behavior for the external command and external application. There are two supported values:

In the empty boilerplate samples shown here, you will see the definition of the manual option in VB.NET (Listing 24.5) and the automatic option in C# (Listing 24.6).

Imports Autodesk.Revit
Imports Autodesk.Revit.UI
Imports Autodesk.Revit.ApplicationServices

<Regeneration(RegenerationOption.Manual)> _
Public Class Application
    Implements IExternalApplication

Public Function OnStartup(ByVal a As UIControlledApplication) _
          As Result Implements IExternalApplication.OnStartup
      Try
          ' Application starts here
          Return Result.Succeeded
      Catch ex As Exception
          Return Result.Failed
      End Try
  End Function

  Public Function OnShutdown(ByVal a As UIControlledApplication) _
      As Result Implements IExternalApplication.OnShutdown
      Return Result.Succeeded
  End Function

End Class

using Autodesk.Revit;
using Autodesk.Revit.UI;
using Autodesk.Revit.ApplicationServices;

[Regeneration(RegenerationOption.Automatic)]
public class Application : IExternalApplication
{
     public Autodesk.Revit.UI.Result OnStartup(ControlledApplication application)
     {
       // OnStartup implementation
     }
     public Autodesk.Revit.UI.Result OnShutdown(ControlledApplication application)
    {
       // OnShutdown implementation
    }
}

One of the more obvious changes made to the API in this release is the renaming of namespaces. These new names help improve consistency and make the API more suitable for future expansion. Most notable are the changes to the MEP namespaces to Mechanical, Electrical, and Plumbing. Figure 24.2 shows a small excerpt from the Revit 2011 API Namespace Remapping.xlsx file included with the Revit 2011 SDK available for download from the Autodesk website.

This figure shows from left to right the class name, the previous 2010 namespace, the new 2011 namespace, and finally any notes explaining the change in the last column of the document. This spreadsheet will help get you on your way to understanding the namespace changes made to the Revit 2011 API.

Figure 24.2. Namespace remapping spreadsheet available with the Revit SDK

Perhaps one of the most powerful improvements made in the Revit 2011 API has to do with the ribbon control additions. The ability to dock a custom text box into the Quick Access toolbar (QAT) for uses ranging from command entry with full argument syntax support to family search is now right at your fingertips. This opens doors for generating simpler customizations without having to create a clunky dialog interface.

All external commands and applications are now required to have unique globally unique identifiers (GUIDs) in order to load into the Revit user interface. This means that each command and application is better managed as individual Visual Studio projects.

Visual Studio allows multiple stand-alone projects to be loaded into a master project, allowing you to easily manage multiple projects written in any supported .NET language in one convenient master environment.

This example demonstrates how to configure the ExternalCommand as one Visual Studio project and the ExternalApplication as another. You will then create a third master project into which you will load the two subprojects.

All Autodesk Revit 2011 IExternalCommands and IExternalApplications now require two namespace references: RevitAPI.dll and RevitAPIUI.dll.

Right-click the title of the Visual Studio 2008 project name in the Solution Explorer and select Add

Figure 24.5. Adding API references to your Visual Studio project

The ExternalApplication project requires two additional references to Presentation Core and Windows Base for the ribbon image functionality. Both of these references are available from the .NET tab of the Add References dialog box.

With the namespace references out of the way, the next step in our project configuration is to name the default IExternalApplication and IExternalCommand interface classes to something logical. The names of these classes can be anything you want but we recommend that a consistent naming strategy be used to make it easier to manage. We typically use the name of Command for commands and App for applications.

Command Class

Select Class1.vb in the ExternalCommand project, and change its name to Command.vb in the Visual Studio properties window. This class will serve as the main external command class containing the IExternalCommand interface necessary to gain access to the Revit user interface.

Setting CopyLocal to False

The CopyLocal property for references added to a project using the Browse method will typically default to True. This property should always be set to False for the Revit API DLLs.

Select the RevitAPI.dll and RevitAPIUI.dll references and set their CopyLocal property to False in the Properties Palette, as shown here:

Import Namespaces

The command class requires three namespace imports. The Revit and Revit.UI namespaces are used to get at the main program and user interface functionalities. The Revit.Attributes namespace is used to access the regeneration and transaction features that are now required by the Revit 2011 API.

Imports Autodesk.Revit
Imports Autodesk.Revit.UI
Imports Autodesk.Revit.Attributes

Transaction and Regeneration Mode Attributes

The Transaction and Regeneration attributes are now required for all Revit 2011 API commands and applications. These two attributes must be called immediately before the class declaration and after any namespace imports.

The transaction serves as a container of changes that can be rolled back if a failure occurs. The regeneration options can now be set to manual, preventing Revit from regenerating on each and every modification made by your utility. This basically opens the door for speed and efficiency in your functions.

<Transaction(TransactionMode.Automatic)> _

<Regeneration(RegenerationOption.Manual)> _
Public Class Command .......

Listing 24.7 shows the completed Command class code.

Example 24.7. The Completed Command Class

Imports Autodesk.Revit
Imports Autodesk.Revit.UI
Imports Autodesk.Revit.Attributes

''' <summary>
''' Demonstrates how an ExternalCommand is added to the Revit user interface.
''' </summary>
<Transaction(TransactionMode.Automatic)> _
<Regeneration(RegenerationOption.Manual)> _
Public Class Command
    Implements IExternalCommand ' All ExternalCommands i
    must implement IExternalCommand
    ' Handy way to post build version info to a form

    Public Const appDate As String = "(YYYY-MM-DD) - "
    Public Const appVer As String = "V#.#"

    Public Function Execute(ByVal commandData As ExternalCommandData, _
                             ByRef message As String, _
                             ByVal elements As DB.ElementSet) _
                             As Result Implements IExternalCommand.Execute
        Try
            Dim rvtApp As UI.UIApplication = commandData.Application
            Dim rvtDoc As DB.Document = rvtApp.ActiveUIDocument.Document
            Dim oForm As New formMain
            Dim sAppVersion As String = rvtDoc.Application.VersionNumber
            ' Pass the Revit document along with any other variables to the form
            oForm.Initialise(rvtApp, rvtDoc, appDate, appVer & i
            " for RAC" & sAppVersion)
            oForm.ShowDialog()
            ' ExecuteCommands must return either Succeeded, Failed, or Cancelled
            Return Result.Succeeded
        Catch ex As Exception
            ' If something goes wrong, exit and return failed
            message = "Command load failed"
            Return Result.Failed
        End Try
    End Function
End Class

Imports Autodesk.Revit.UI
Imports Autodesk.Revit.UI.Events
Imports Autodesk.Revit.Attributes

Imports System.Windows.Forms
Imports System.Windows.Media.Imaging
Imports System.Reflection

<Transaction(TransactionMode.Automatic)> _
<Regeneration(RegenerationOption.Manual)> _
Public Class App ......

Imports Autodesk.Revit.UI
Imports Autodesk.Revit.UI.Events
Imports Autodesk.Revit.Attributes
Imports System.Windows.Forms
Imports System.Windows.Media.Imaging
Imports System.Reflection
''' <summary>
''' Demonstrates how an ExternalApplication is added to the Revit user interface.
''' </summary>
<Transaction(TransactionMode.Automatic)> _
<Regeneration(RegenerationOption.Manual)> _

Public Class App
    ' Required Interface...
    Implements IExternalApplication
    ' Fired off by OnStartup
    Public Sub AddRibbonPanel(ByVal a As UIControlledApplication)
        ' Share the execution path with supplemental command paths
        Dim myPath As String = Assembly.GetExecutingAssembly.Location.Substring( _
            0, (Assembly.GetExecutingAssembly.Location.LastIndexOf("") + 1))
        Dim rvtPanel As RibbonPanel = a.CreateRibbonPanel("Samples")
        ' Use the 'New' method to create pushbuttons
        Dim rvtData As New PushButtonData("ExampleCommand", _
            "Batch Family Export Utility", _
            myPath & "ExampleCommand.dll", _
            "ExampleCommand.Command")
        rvtData.ToolTip = "Example Batch Family Export Command"
        ' Add the pushbutton to the ribbon panel
        Dim myButton As PushButton = rvtPanel.AddItem(rvtData)
        ' Add a textbox that will return its entered value when enter is pressed
        Dim txtData As New TextBoxData("MyTextBox")
        ' Add the textbox to the ribbon panel
        Dim txtBox As Autodesk.Revit.UI.TextBox = rvtPanel.AddItem(txtData)
        txtBox.Value = "Textbox Event Example"
        txtBox.Image = New BitmapImage(New Uri(myPath & "enter.png"))
        txtBox.ToolTip = "A sample message dialog displaying the entered data..."
        txtBox.ShowImageAsButton = True
        txtBox.PromptText = "Enter Text and Press Enter"
        ' This passes the event data to our event handler function
        AddHandler txtBox.EnterPressed, _
            New EventHandler(Of TextBoxEnterPressedEventArgs)i
           (AddressOf Me.TextBoxPopup)
    End Sub

    Public Sub TextBoxPopup(ByVal sender As Object, _
                            ByVal args As TextBoxEnterPressedEventArgs)
        ' This reacts with the string entered into the textbox...
        MessageBox.Show(sender.value, _
                        "Textbox Value!", _
                        MessageBoxButtons.OK, _
                        MessageBoxIcon.Exclamation)
    End Sub

    Public Function OnStartup(ByVal a As UIControlledApplication) _
    As Result Implements IExternalApplication.OnStartup
        Try
            ' Add the ribbon part to the Add-Ins tab
            AddRibbonPanel(a)

Return Result.Succeeded
     Catch ex As Exception
         Return Result.Failed
        End Try
    End Function

    Public Function OnShutdown(ByVal a As UIControlledApplication) _
        As Result Implements IExternalApplication.OnShutdown
        Return Result.Succeeded
    End Function

End Class

The User Form

The sample command will need a user form as a means to interact with the user. Right-click ExternalCommand in the Solution Explorer and select Add

Adding the Controls

The next step is the design of the user form along with all required controls necessary to provide the functionality we need. Save the project and open the design view of the formMain class. Figure 24.6 illustrates what the completed form design should look like.

Figure 24.6. Example of a completed form in Visual Studio

You can be creative as to your placement of these controls so long as they are of the correct control types and match the names listed here. The controls are listed in order from top to bottom, going left to right, as illustrated in the previous example.

FolderBrowserDialog Control: FolderBrowserDialog1

Add a FolderBrowserDialog from the toolbox to the form named FolderBrowserDialog1. This will serve as a helper dialog box to navigate and select an alternate directory for the RFA file family exports. This control only displays in the form design tray and will not necessarily display on the form itself.

Progressbar Control: ProgressBar1

Provides progress information to user. Place this control along the top of the form as illustrated earlier.

Label Control: LabelExport

The example form design shows the LabelExport control placed underneath the left corner of the progress bar along the top of the form. This label displays as the main prompt to the user on load.

Button Control: ButtonBrowse

Place this control beneath the progress bar and set its text to .... This button will be used to launch the folder browse dialog box. Double-click the ButtonBrowse control and enter the following code:

Private Sub ButtonBrowse_Click(ByVal sender As System.Object, _
                               ByVal e As System.EventArgs) _
                               Handles ButtonBrowse.Click
    ' Browse to select the parent export path
    Me.FolderBrowserDialog1.ShowDialog()
    If Me.FolderBrowserDialog1.SelectedPath.ToString() <> "" Then
        Me.LabelExportPath.Text = 

        Me.FolderBrowserDialog1.SelectedPath.ToString()
    End If
End Sub

Label Control: LabelExportPath

Place a label control named LabelExportPath to the right of the ButtonBrowse control. This label will display the path to the selected export directory.

Label Control: LabelFileName

Place a label control beneath the ButtonBrowse button named LabelExport. This label will display the current family file as it is being processed by the main export functions.

Button Control: ButtonExport

The bottom-left button, named ButtonExport, is used to launch the export command and commit the start of the export process. Set the text for this button to Export all Families. Double-click this button control to create the basic code structure for the click event. The code behind this button is shown in "The Main Export Function" section later in this chapter.

Button Control: ButtonCancel

The bottom-right button, named ButtonCancel, is used to close the command without performing any actions at all. Set the text for this control to Cancel. Double-click the Cancel button and enter the following code:

Private Sub ButtonCancel_Click(ByVal sender As System.Object, _
                               ByVal e As System.EventArgs) _
                               Handles ButtonCancel.Click
    Me.Close()
End Sub

Adding the Private Form Class Variables

The following lines are used to make the Revit application, current Revit project model, and default export path available to all functions within the form class. These declarations will go just beneath the form class declaration:

Private rvtDir As String = ""
Private rvtApp As UI.UIApplication = Nothing
Private rvtDoc As DB.Document

Adding the Supplemental Form Functions

The command example is quite simple in function but still requires a few supplemental helper functions:

Initialization

It is common to utilize an initialization subroutine within a form as a means of introducing any required parameters to the form as it is being launched. This provides an easy way to pass object variables to the form that can then be used within the form class.

Among the objects that we are interested in passing over to the user form are the Revit application object, current Revit project model, a string representing the build date, and another string representing an arbitrary build version, such as V1.0.

This function will also set our default export path to the directory of our model using the central model file path if the project is workshared.

Public Sub Initialise(ByVal app As UI.UIApplication, _
                      ByVal document As DB.Document, _
                      ByVal myAppDate As String, _
                      ByVal strAppVer As String)
    ' Hide the progressbar until we need it
    Me.ProgressBar1.Visible = False
    ' Form title with version
    Me.Text = "Batch Family Exporter - " & myAppDate & strAppVer
    ' Expose Revit doc and app
    rvtDoc = document
    rvtApp = app
    ' Set default export path adjacent to model location
    ' If workshared, use the central model path
    If rvtDoc.IsWorkshared = True Then
        Try
            rvtDir = Path.GetDirectoryName i
           (rvtDoc.WorksharingCentralFilename) _
           & "/Exported Families/"
       Catch ex As Exception
           ' Detached model will not have a file path
       End Try
    Else
       rvtDir = Path.GetDirectoryName(rvtDoc.PathName) & _
       "/Exported Families/"

End If
    ' The proper formatted file path...
    Me.LabelExportPath.Text = Replace(rvtDir, "/", "")
End Sub

CheckValidFileName

While Revit provides its own means of preventing invalid file-naming characters from making their way into family names, you can use this function as a precautionary means. This filename validity snippet is useful anytime you are exporting files and need to verify that the characters used in the filename are valid.

Public Shared Function CheckValidFileName

   (ByVal fileName As String) As String
   CheckValidFileName = fileName
   For Each c In Path.GetInvalidFileNameChars()
       If fileName.Contains(c) Then
           ' Invalid filename characters detected...
           ' Could either replace characters or return empty
           CheckValidFileName = ""
       End If
    Next
    Return CheckValidFileName
End Function

The Main Export Function

The main export function in the sample project is all nested inside the ButtonExport_Click subroutine. There will be a lot going on inside this routine. The meat of the function is where the family symbols are filtered out of the Revit document and then iterated one by one and exported out as external RFA family files into a subdirectory named using the family's Revit category name.

The Element Collection Filter

The Revit 2011 API provides a much more efficient and robust means of filtering elements for selection as well as iterating elements within these collections.

' Filter to get a set of elements that are elementType
Dim filter As New DB.ElementIsElementTypeFilter
Dim collector As New DB.FilteredElementCollector(rvtDoc)
collector.WherePasses(filter)

Element Iteration

Once the elements have been gathered from the model using an element filter, we can iterate through them quite easily. This snippet illustrates the element iteration code:

Dim iter As IEnumerator = collector.GetElementIterator
Dim element As DB.Element
Dim FamInst As DB.Family = Nothing
Dim famSymb As DB.FamilySymbol = Nothing
Dim category As DB.Category
Do While (iter.MoveNext())
   element = iter.Current

If (Type Of element Is DB.FamilySymbol) Then
       category = element.Category
       If Not (category Is Nothing) Then
           Try ' Create the category subdirectory
               exportPath = rvtDir & category.Name & "/"
               Directory.CreateDirectory(Replace _
               (exportPath, "/", "", , , CompareMethod.Text))
          Catch ex As Exception
              ' Category subdirectory exists
          End Try
          Try ' family variable to Element
              famSymb = element
              FamInst = famSymb.Family
              sFamName = FamInst.Name
              ' Verify famname is valid filename and exists
              If Dir$(exportPath + sFamName & ".rfa") = "" And _
                      CheckValidFileName(sFamName) <> "" Then
                  Me.LabelFileName.Text = "..." & _
                      category.Name & "" & _
                      FamInst.Name
                  Dim famDoc As DB.Document = rvtDoc.EditFamily(FamInst)
                  famDoc.SaveAs(exportPath + sFamName & ".rfa")
                  famDoc.Close(False)
              End If
          Catch ex As Exception
              ' Prevent hault on system families
           End Try
       End If
   End If
Loop

Listing 24.9 shows the completed formMain code.

Example 24.9. The Completed formMain Code

Imports Autodesk.Revit
Imports System.IO

Public Class formMain

    Private rvtDir As String = ""
    Private rvtApp As UI.UIApplication = Nothing
    Private rvtDoc As DB.Document

    Public Sub Initialise(ByVal app As UI.UIApplication, _
                          ByVal document As DB.Document, _
                          ByVal myAppDate As String, _
                          ByVal strAppVer As String)

' Hide the progressbar until we need it
        Me.ProgressBar1.Visible = False
        ' Form title with version
        Me.Text = "Batch Family Exporter - " & myAppDate & strAppVer
        ' Expose Revit doc and app
        rvtDoc = document
        rvtApp = app
        ' Set default export path adjacent to model location
        ' If workshared, use the central model path
        If rvtDoc.IsWorkshared = True Then
            Try
                rvtDir = Path.GetDirectoryName

                (rvtDoc.WorksharingCentralFilename) _
                & "/Exported Families/"
            Catch ex As Exception
                ' Detached model will not have a file path
            End Try
        Else
            rvtDir = Path.GetDirectoryName(rvtDoc.PathName) & _
            "/Exported Families/"
        End If
        ' The proper formatted file path...
        Me.LabelExportPath.Text = Replace(rvtDir, "/", "")
    End Sub

    Public Shared Function CheckValidFileName(ByVal fileName As String) As String
        CheckValidFileName = fileName
        For Each c In Path.GetInvalidFileNameChars()
            If fileName.Contains(c) Then
                ' Invalid filename characters detected...
                ' Could either replace characters or return empty
                CheckValidFileName = ""
            End If
        Next
        Return CheckValidFileName
    End Function

    Private Sub ButtonExport_Click(ByVal sender As System.Object, _
                               ByVal e As System.EventArgs) _
                               Handles ButtonExport.Click
        ' Return a qualified export path
        rvtDir = Replace(rvtDir, "", "/", , , CompareMethod.Text)
        Dim sFamName As String = ""
        Dim exportPath As String = ""
        Try ' If the parent export directory is missing, create it
            Directory.CreateDirectory _
            (Replace(rvtDir, "/", "", , , CompareMethod.Text))
        Catch ex As Exception

' Message to show any errors
            MsgBox(Err.Description, MsgBoxStyle.Information, Err.Source)
        End Try
        ' Filter to get a set of elements that are elementType
        Dim filter As New DB.ElementIsElementTypeFilter
        Dim collector As New DB.FilteredElementCollector(rvtDoc)
        collector.WherePasses(filter)
        ' Iterate the elements
        Dim iter As IEnumerator = collector.GetElementIterator
        ' Variables for element handling
        Dim element As DB.Element
        Dim FamInst As DB.Family = Nothing
        Dim famSymb As DB.FamilySymbol = Nothing
        Dim category As DB.Category
        ' Quickly count for progress bar
        Dim iCntFam As Integer = 0
        Dim iCnt As Integer = 0
        Do While (iter.MoveNext())
            element = iter.Current
            If (TypeOf element Is DB.FamilySymbol) Then
                iCntFam += 1
            End If
        Loop
        ' Reset for export process
        iter.Reset()
        ' Start the progressbar
        Me.ProgressBar1.Visible = True
        Me.ProgressBar1.Minimum = 0
        Me.ProgressBar1.Maximum = iCntFam
        Me.ProgressBar1.Value = iCnt
        ' The export process
        Do While (iter.MoveNext())
            element = iter.Current
            If (TypeOf element Is DB.FamilySymbol) Then
                Me.ProgressBar1.Value = Me.ProgressBar1.Value + 1
                category = element.Category
                If Not (category Is Nothing) Then
                    Try ' Create the category subdirectory
                        exportPath = rvtDir & category.Name & "/"
                        Directory.CreateDirectory(Replace _
                         (exportPath, "/", "", , , CompareMethod.Text))
                    Catch ex As Exception
                        ' Category subdirectory exists
                    End Try
                    Try ' family variable to Element
                        famSymb = element
                        FamInst = famSymb.Family
                        sFamName = FamInst.Name

' Verify famname is valid filename and exists
                        If Dir$(exportPath + sFamName & ".rfa") = "" And _
                                CheckValidFileName(sFamName) <> "" Then
                           Me.LabelFileName.Text = "..." & _
                               category.Name & "" & _
                               FamInst.Name
                           Dim famDoc As DB.Document = 

                            rvtDoc.EditFamily(FamInst)
                           famDoc.SaveAs(exportPath + sFamName & ".rfa")
                           famDoc.Close(False)
                       End If
                   Catch ex As Exception
                       ' Prevent hault on system families
                   End Try
               End If
           End If
        Loop
        Me.Close()
    End Sub

    Private Sub ButtonCancel_Click(ByVal sender As System.Object, _
                                   ByVal e As System.EventArgs) _
                                   Handles ButtonCancel.Click
        Me.Close()
    End Sub

    Private Sub ButtonBrowse_Click(ByVal sender As System.Object, _
                                   ByVal e As System.EventArgs) _
                                   Handles ButtonBrowse.Click
        ' Browse to select the parent export path
        Me.FolderBrowserDialog1.ShowDialog()
        If Me.FolderBrowserDialog1.SelectedPath.ToString() <> "" Then
            Me.LabelExportPath.Text = 

             Me.FolderBrowserDialog1.SelectedPath.ToString()
        End If
    End Sub
End Class

One simple example of a journal script is the family upgrade utility, which is a simple journal-based script that will launch Revit and open a series of families you specify, thus upgrading them to the latest version. This utility is included with your Revit installation package and can be found after you extract the installation package in the subfolder: UtilitiesCommonContentBatchUtility.

Before running the script, you must first copy the Upgrade_RFA.txt and Upgrade_RFA.bat files into the root directory of the library you want to upgrade and then run the Upgrade_RFA.bat file to generate a list of files to upgrade. This BAT routine will create another text file named famlist_rfa.txt; don't change the name of this file or move it. The Upgrade_RFA.txt file is a Revit journal file. If you open the journal file, you will find the main function listed as a subroutine between the code Sub and End Sub, as shown in Listing 24.10.

Sub upgrade(namepath, file)

Jrn.Command "Menu", "Open an existing project , 57601 , ID_FILE_OPEN"
  Jrn.Data "File Name" _
          , "IDOK", namepath

  Jrn.Command "Internal" , " , ID_REVIT_SAVE_AS_FAMILY"

Jrn.Data "File Name" , "IDOK", namepath

  Jrn.Command "Menu" , "Close the active project , ID_REVIT_FILE_CLOSE"
End Sub

To execute the journal script, simply drag the Upgrade_RFA.txt file onto the Revit desktop icon. Revit will launch and open each RFA file in the list. As you can see in Listing 24.10, the actual journal commands being passed to Revit are quite simple. ID FILE OPEN opens the project, whereas ID REVIT SAVE AS FAMILY saves it in the new version.

You can find another example of journal scripting in a local file utility developed in collaboration between David Baldacchino, David Kingham, and James Vandezande. This utility was created in an open source scripting language called AutoHotkey (www.autohotkey.com). This language is easy to learn and can be an excellent learning platform for aspiring programmers. You can download the local file utility from the AUGI Forums at forums.augi.com/showthread.php?t=65897.

The local file utility has several iterations for each of the developer's respective companies, but at its core, it performs basic file functions to create local copies of Revit central files and then automatically opens them with journal-based scripts. Let's take a look at that portion of the utility.

Other parts of the script will identify the central file and locations for a user's local copies. Once a local copy of the central file has been created, journal commands are generated and written to an actual journal file:

Set Jrn = CrsJournalScript
Jrn.Command "Menu" , "Open an existing project , 57601 , ID_REVIT_FILE_OPEN"
Jrn.Data "File Name" _
, "IDOK", "%DESTINATION%\%LOCALFILE%.rvt"
Jrn.Data "WorksetConfig" _
, "Editable", 0
  Jrn.Data "MessageBox" _
         , "IDOK", "This Central File has been copied or moved from 

  ""%DRV%\%DSCPLN%\%Folder%\%C1%"" to ""%DESTINATION%\%LOCALFILE%.rvt""."

  & vbCrLf & "" & vbCrLf & "If you wish this file to remain a Central File 

  then you must re-save the file as a Central File. To do this select 

  ""Save As"" from the ""File"" menu and check the ""Make this a Central 

  File after save"" check box (under the options button) before you save."

  & vbCrLf & "" & vbCrLf & "If you do not save the file as a Central File

  then it will be considered a local user copy of the file belonging to

  user ""%USERNAME%""."
Jrn.Command "Menu" , "Workset control , 33460 , ID_SETTINGS_PARTITIONS"

The journal file is then executed by passing it to the Revit program executable, which is similar to actually dropping a journal file on the Revit desktop icon in the family upgrade method.

Notice the syntax of the journal launching code is quite similar to running an application with optional parameters at the Windows command prompt. The following line runs Revit.exe with the journal file (%JournalFile%) in a maximized application window:

Run %AppPath%ProgramRevit.exe "%JournalFile%", Max