Delete Empty Elevation Marker Tags

It is pretty common for a model to end up with a bunch of abandoned elevation marker tags. There are a bunch of ways that this can happen and depending on how you have your elevation tag symbols defined can be difficult to find visually for removal.

One of the supreme beings that I used to work with at CASE built a means of doing this in Dynamo.

This is a simple routine that finds these and eradicates them from your model...

Getting all File Based Family Elements by Category

I haven't shared any code on here in a while and thought this might be a good time to get back in the general sharing mode. I get asked a bunch about how the best way is to collect elements in the model especially file based component families (FamilySymbol).

This sample should work in Revit 2012 as well as Revit 2013.

Here's a quick and easy way to get all elements in your model of FamilySymbol organized by Category. We'll use a basic Dictionary class to hold the elements since Dictionaries are super fast to access values from without any iteration required.

First you will need to declare your dictionary somewhere in your code as either a private or public property (you decide), I'm using a property in this example.

  ''' <summary>

  ''' All Family Symbol Elements in the Model by Category

  ''' </summary>

  ''' <value></value>

  ''' <returns></returns>

  ''' <remarks></remarks>

  Public Property FamilySymbolElements As Dictionary(Of Category, List(Of FamilySymbol))

The next thing is to provide a subroutine where you can perform the gathering of the elements. After we instantiate a fresh dictionary to hold the data, we build a filtered element collector that collects elements by their class type. The class type we're interested in is FamilySymbol.

We then iterate over the elements returned by the collector and check if the category that the element belongs to is in our dictionary. Where the category does not exists as a key in our dictionary, we add a fresh list containing the single element. Where it already exists, we get the list containing the elements and add the new element to the list and apply the updated list back as the value to the dictionary for that category.

  ''' <summary>

  ''' Get all Family Symbol Elements

  ''' </summary>

  ''' <remarks></remarks>

  Private Sub GetSymbols()

    ' Fresh Dictionary

    FamilySymbolElements = New Dictionary(Of Category, List(Of FamilySymbol))

    ' Collector

    Using col As New FilteredElementCollector(Doc)

      col.OfClass(GetType(FamilySymbol))

      For Each x In col.ToElements

        Try

          ' Cast and Collect

          Dim m_fs As FamilySymbol = TryCast(x, FamilySymbol)

          ' Does the Category already exist in the system

          Dim m_cat As Category = x.Category

          If Not FamilySymbolElements.ContainsKey(m_cat) Then

            ' New List

            Dim m_l As New List(Of FamilySymbol)

            m_l.Add(m_fs)

            FamilySymbolElements(m_cat) = m_l

          Else

            Try

              ' Updated List

              Dim m_l As New List(Of FamilySymbol)

              FamilySymbolElements.TryGetValue(m_cat, m_l)

              m_l.Add(m_fs)

              ' Update the Key

              FamilySymbolElements(m_cat) = m_l

            Catch ex As Exception

            End Try

          End If

        Catch ex As Exception

        End Try

      Next

    End Using

  End Sub

Now we have a complete list of FamilySymbol elements in the model organized by category.

Hands on Revit API Training Workshops

Updated July 6, 2012!


I've got some good news for those of you interested in learning the Revit API. I will be conducting a series of hands-on workshops at the CASE office in New York (401 Broadway). These workshops will max out at ten (10) attendees. You will leave this workshop capable of developing your own add-ins.

Content will be tailored for beginner programmers that have familiarity with Revit. If you are a designer or support designers and have some sort need to learn BIM automation, this workshop is for you.

MacBook Airs loaded with all necessary software will be provided for your use during the workshops... just show up and be ready to learn!

When?

Look for an official announcement later this month with the first workshop being held some time in August.

Length of Workshop?

We anticipate the workshop running 4 days with each session day running six hours with an hour long break in the middle (9am to 4pm).

Talent Assumptions / Prerequisites

• Attendees will have basic knowledge of the Revit platform
• Attendees have at least hear of the Revit API and have heard of the Microsoft .NET Framework

Programming Languages Used in Workshop

• C# and VB.NET

Cost?

The cost for the workshops is yet to be determined. Stay tuned for announcements from the www.case-inc.com site.

Want to Reserve a Spot Now?

• Leave a comment at the bottom with your name
• DM or @ me on Twitter: AYBABTM

Revit API 101.2

The topic for this post will be centered on the .addin manifest file and how Add-Ins get loaded into the Revit session. The schema or file organization of the .addin file format will be discussed at first and then I'll explain a little bit about the options you have for configuring the manifest file up so that it loads the resources necessary for your tool to run automatically during debug.

Sorry if you've been hoping for a video, but this kind of information is best absorbed through good old fashioned black and white. And as far as language examples, these concepts are virtually identical between C# and VB.NET.

What is the .addin Manifest File?

For those of you that have experience using Revit Add-Ins in versions prior to Revit 2010, you may remember the old cryptic method of loading an Add-In by editing the Revit.ini file. The old Revit.ini method of loading Add-Ins into Revit is now obsolete and replaced by what is referred to as a manifest file. Manifest files are XML formatted ASCII files that tell Revit where the Add-In resources are and what class that the required IExternalApplication, IExternalCommand, or IExternalDBApplication interface has been implemented so that Revit can load the necessary commands and functionality into the session.

Revit searches for .addin files in two locations. The directory paths shown here are for Windows 7. Replace the YYYY in the paths below to match your Revit 2010 or higher installation versions (2010, 2011, 2012, 2013, etc.).

Constant for all users on the machine (may require admin permissions to modify)

• C:\ProgramData\Autodesk\Revit\Addins\YYYY

Current user logged into Windows only (does not require admin permissions to modify)

• %USERPROFILE%\AppData\Roaming\Autodesk\Revit\Addins\YYYY

Required Manifest Tags

There are slightly different requirements between command and application load manifests and quite a few optional tags that you can utilize in your .addin manifest files. This section will focus on the required tags. First I'll outline the required tags that are consistent for both application and command loading manifests and then the one tag specific to application load sequences.

Assembly (Required all All)

This tag is required for all kinds of applications and commands. It must contain the full file name to your DLL file. It is only required to contain a full path to the DLL if the DLL does not exist within the same directory as the .addin file. Relative pathing is supported by entering ".\" before the file path and or name so long as the directory is located beneath the same directory that the .addin file resides.

ClientId (Required for All)

A complete and fully qualified global unique identifier is required in this tag. This GUID needs to be unique across all other application or command ClientId's loaded in your session.

FullClassName (Required for All)
This is where you would enter the namespace(s) followed by the class name that contains the command or application interface that you want to execute or load. This tag should never have any spaces contained in it.

VendorId (Required for All Revit 2012 and Higher)
The four digit registered developer ID that can be obtained from the ADN site to identify the developer.

VendorDescription (Required for All Revit 2012 and Higher)
An explanation or description for the developer. It is common to list the company name and or the web address to a support site that relates to the tool.

Name (Applications Only)
A unique name for the application.

A Sample Manifest File

As you can see in the sample .addin file below, it is possible to nest multiple command and applications load sequences into a common .addin file. A sample application load sequence is loaded first with a command after it. The important thing to remember when combining multiple command or application loads is that they are all nested inside a single "RevitAddIns" tag.

<?xml version="1.0" encoding="utf-8"?>
<RevitAddIns>
  <AddIn Type="Application">
    <Name>Application Name</Name>
    <Assembly>Namespace.dll</Assembly>
    <ClientId>4ea76ff3-bba7-4969-9371-c7a3eb8ac0a8</ClientId>
    <FullClassName>Namespace.Class</FullClassName>
    <VendorId>XXXX</VendorId>
    <VendorDescription>Something about the developer, Link</VendorDescription>
  </AddIn>
  <AddIn Type="Command">
    <Text>My Command Name</Text>
    <Description>Example Command Description</Description>
    <Assembly>Namespace.dll</Assembly>
    <FullClassName>Namespace.CommandClass</FullClassName>
    <ClientId>9db2c58d-33f2-4ad1-8932-329dd83a4d0a</ClientId>
    <VendorId>XXXX</VendorId>
    <VendorDescription>Something about the developer, Link</VendorDescription>
  </AddIn>
</RevitAddIns>

Automatic Copying of a Solution Manifest to Install on Debug

You can have your .addin manifest copied to your .addins load directory automatically while debugging in Visual Studio by setting a post build event. This requires that your .addin file exist in the root of your project and included within your project's solution. An example on where and how to enter this to work on a Visual Basic .NET example is shown below.

Note: If you left out a file path to your assembly (file name only), you will be able to debug from your debug directory location during debug mode as well as run the main DLL in your Add-In load directory using the same manifest file. You will need to adjust command below to match the Revit version year and .addin file name as required. Just remember, you will need to include your .addin file withini your Visual Studio solution for this trick to work.


copy "$(ProjectDir)MyAddinFile.addin"
"$(AppData)\Autodesk\REVIT\Addins\2012\MyAddinFile.addin"

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

How To Uninstall or Remove a Revit Add-In

I've been getting this question quite a bit recently:
"How do I remove an Add-In from Revit?"

This post will not focus on what an Add-In is nor what an Add-In manifest is... hopefully you already have an idea or can find out about those things here.

The uninstall solution depends on the version of Revit that you are running. The method that I will discuss in this post is suitable for Revit 2011 and newer. If you are using Revit 2010 then you just need to go ahead and upgrade your shiz.

There are two locations that Add-In manifests can be placed to load into Revit. The paths shown below are for Windows7. If you are still running Windows XP than it may be time to update your other shiz.

Machine Wide Location
The first is available to all users that log into the machine and requires administrative privileges to add files to.

• C:\ProgramData\Autodesk\Revit\Addins\

User Profile Location

The user profile location will only load for the current user. This location does not require administrative privileges and therefor anyone can install Revit Add-Ins into their environment if they use this location.

• %USERPROFILE%\AppData\Roaming\Autodesk\Revit\Addins\

Preventing the Add-In from Loading
There's a bunch of ways to prevent an Add-In from loading into Revit.

• Removing the associated .addin file from either of the locations mentioned above will prevent the Add-In from loading into Revit. You can leave the .dll and all other files there if you want and they will not load without the associated .addin file instructing Revit to do so.
• Another trick is to simply rename the extension of the .addin file to something like .addin.notloaded or something to keep it from loading.
• Revit 2011 and 2012 do not load .addin files that are placed in sub-directories of these Add-In manifest directories either, so you could just simply create a sub-directory for the Add-Ins that you don't want to be loaded and place them in that sub directory.

How to Build a ClickOnce Installer for Revit Add-Ins

Have you ever wanted to deploy an installation package that did not required Admin privileges for the distribution of your Revit Add-ins? Do you also need a simple means to deploy frequent updates? ClickOnce installers can do just that for you.

Microsoft unveiled the ClickOnce technology way back in 2003 and is great so long as your application is simple and does not require any modifications during install that may require administrative access. ClickOnce works by copying an entire isolated application to the user's profile on install. There is a small issue in that ClickOnce is not available for class library projects (Revit Add-Ins are class library projects).

Here is a workaround that you can use to deploy a ClickOnce application to install your Revit Add-Ins.

From inside your current Revit Add-In Visual Studio solution, add a new Windows Console project named the same as your target project but with a ".Updater" suffix added to the end. Save this new project alongside your current project. This new console project will only be used to copy the Revit Add-In program files into the user's Revit Add-Ins directory under their Windows user profile.

This new project will allow you to generate the published installer that a standard class will not. Open the project settings and click on the "Publish" tab along the left (VB.NET, C# will be different). You can enter a version setting as well as an installation URL where youy will post your updates.

Notice the highlighted path above in the URL section? You need to also enter this in the "Updates" section. Click on the "Updates" button to access the optional updates settings.

You can set the project and publisher settings from the "Options" button shown here.

The next thing that you need to do is add a reference to your main project so that the resulting dll files can be included as part of the installation of this console project. Add a reference to your console project and choose your project from the Projects tab.

Now that you have a reference to this project, you can add the output dll to your ClickOnce installation process. From the Publish tab, click the "Application Files" button and make sure that everything required by your Revit-Add-In is also available within this dialog. Set each file to "Include" that you will require in your main installation.

You may have noticed that the ".addin" file is included in the above list. Be sure to add your addin file to the console project so that it can be included in this list as it is required in order for the Revit Add-In to launch in a Revit session.

You can also add an icon to be used by your installer if you like by setting an icon in the "Application" tab of the console project.

Now that you've got the basic format of the publish project configured, you'll need some code to copy the files into the user's Revit Add-Ins directory. Enter the following code in the default "Module1" that was created automatically in your new console project to do just that:

Imports System.IO
Imports System.Reflection

Module mod1

    Private m_sourcePath As String = Path.GetDirectoryName(Assembly.GetExecutingAssembly.Location)
    Private m_w7 As String = Environment.GetEnvironmentVariable("UserProfile") & "\AppData\Roaming\"
    Private m_xp As String = Environment.GetEnvironmentVariable("UserProfile") & "\Application Data\"

    ''' <summary>
    ''' The Main Function
    ''' </summary>
    ''' <remarks></remarks>
    Sub Main()
        ' Test for Win7
        If Directory.Exists(m_w7) Then
            DoCopy(m_w7)
            Exit Sub
        End If
        ' Test for XP
        If Directory.Exists(m_xp) Then
            DoCopy(m_xp)
            Exit Sub
        End If
        ' Warn on Failure
        MsgBox("Your Operating System was not Properly Detected", MsgBoxStyle.Exclamation, "Installation Failed")
    End Sub

    ''' <summary>
    ''' Copy the Files
    ''' </summary>
    ''' <param name="p_destination"></param>
    ''' <remarks></remarks>
    Private Sub DoCopy(p_destination As String)
        ' Addin path
        Dim m_PathAddin As String = p_destination & "Autodesk\Revit\Addins\2012"
        ' Get Files
        Dim m_di As New DirectoryInfo(m_sourcePath)
        Dim m_FilesAddin As FileInfo() = m_di.GetFiles("*.addin")
        Dim m_FilesDll As FileInfo() = m_di.GetFiles("*.dll")
        For Each x In m_FilesAddin
            Try
                x.CopyTo(m_PathAddin & "\" & x.Name, True)
            Catch ex As Exception
                ' Quiet Fail
            End Try
        Next
        For Each x In m_FilesDll
            Try
                x.CopyTo(m_PathAddin & "\" & x.Name, True)
            Catch ex As Exception
                ' Quiet Fail
            End Try
        Next
    End Sub

End Module

After you've made all the necessary adjustments, you can click the "Publish Now" button in the Publish tab to publish the project. A new Publish directory will be created beneath the directory where your new console project was saved. This is your ClickOnce installer? Copy the entire set of files to either a location on your network or to an FTP on the web where you will host the installations. The ".application" file is the installer. Setup.exe can be used for browsers other than IE.

Each subsequent time that you update your code, click the "Publish Now" button to create a new publish installer. Each sequence will be saved in the same location. Copy the updated files to the location where you are hosting your updates and will become available to your users by executing the "updater" program that was originally installed on your client's machines (Executing the tool from inside Revit will NOT automatically update the tools in this configuration).

Be sure and use Internet Explorer to run the "*.application" ClickOnce installer as this is the only browser that will support this technology so far.

Check a String for Valid File Naming Characters

Here's a super simple solution to a surprisingly common problem for validating file naming strings using .NET.

If you have ever required a user to enter a file name and had to validate the characters they entered, I'm sure you have some sort of function that can do this. Surprisingly though, I see a bunch of code where people build their own file name character validation functions.

There is a built-in .NET function for validating file naming characters available from the System.IO namespace. The snippet below shows a very basic use of this command accepting an input of a string to validate and returns the same string back out if valid and an empty string if invalid file naming characters are detected.

    ''' <summary>
    ''' Make sure the path does not contain any invalid file naming characters
    ''' </summary>
    ''' <param name="fileName">The Filename to check</param>
    ''' <returns>A string</returns>
    ''' <remarks></remarks>
    Private Function CheckValidFileName(ByVal fileName As String) As String
        For Each c In Path.GetInvalidFileNameChars()
            If fileName.Contains(c) Then
                ' Invalid filename characters detected...
                ' Could either replace characters or return empty
                Return ""
            End If
        Next
        Return fileName
    End Function

You can call this function like:

If CheckValidFileName(m_string) = "" Then Throw New Exception

If an empty string is returned, you've got invalid characters in the file name...